---
title: "Calendar"
description: "The Calendar is a component to display a calendar to pick a day in multiple calendar systems, such as: Gregorian, Ethiopic, Nepali and many other calendrical systems."
url: https://developers.dhis2.org/docs/ui/components/calendar
source: https://github.com/dhis2/developer-portal/edit/main/docs/ui/components/calendar.md
---

# Calendar

The Calendar is a component to display a calendar to pick a day in multiple calendar systems, such as: Gregorian, Ethiopic, Nepali and many other calendrical systems.

The component is built on top of [multi-calendar-dates](https://github.com/dhis2/multi-calendar-dates/tree/beta) which is an internal library to abstract date-related operations (i.e. calendars, period selectors, date math etc..). The library itself relies on the [Temporal proposal](https://tc39.es/proposal-temporal/#sec-temporal-intro). The proposal (currently at Stage 3 draft) aims to improve built-in support for dates and times in browsers, addressing challenges such as support for timezones, DST-safe artithemtic, string serialization and interoperability via standardized formats, and full support for non-Gregorian calendars.

Here are some sample calendars built with this UI component. Check [StoryBook](pathname:///demo/?path=/story/calendar--with-ethiopic) to play with all the options available for building a Calendar.

## Ethiopic calendar

Ethiopic calendar with narrow day names, short day names and localised to English.

### Narrow day names

[Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

To display the calendar with short day names, use the codeblock below. For the narrow day names remove the `weekDayFormat` prop. For the English locale, use the `en` locale and the short `weekDayFormat`.

```jsx
<Calendar
    calendar="ethiopic"
    locale="am-ET"
    numberingSystem="ethi"
    timeZone="Europe/London"
    weekDayFormat="narrow"
/>
```

## Nepali calendar

:::note
Nepali is a custom calendar not natively implemented in Temporal and Nepali locale is not natively supported by browsers' Internationalization standard. We are providing a custom implementation for the calendar, as well as the localised values. The only two locales allowed are: `ne-NP` (nepali) and `en-NP` (nepali transliterated in latin characters).
:::

Nepali calendar with Napali characters.

[Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

```jsx
// Napali
<Calendar calendar="nepali" locale="ne-NP" timeZone="Europe/London" />
```

Nepali calendar transliterated into latin characters.
[Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

```jsx
// Nepali transliterated in latin characters
<Calendar
    calendar="nepali"
    locale="en-NP"
    timeZone="Europe/London"
    weekDayFormat="short"
/>
```

## Gregorian calendar

Gregorian calendar localised in English, Arabic (Tunisia), Arabic (Sudan), Arabic (Iraq) and Amharic.

**English**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

**Arabic (Tunisia)**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

**Arabic (Sudan)**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

**Arabic (Iraq)**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

**Amharic**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

To display the calendar with a specific locale, use the codeblock below. Adjust the locale to the desired language.

```jsx
<Calendar calendar="iso8601" locale="en" timeZone="Europe/London" />
```

## Other calendars

Some other calendars: Islamic in Arabic, Indian in English and Persian in Farsi

**Islamic in Arabic**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

**Indian in English**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

**Persian in Farsi**

        [Interactive demo: calendar--basic](https://developers.dhis2.org/demo/?path=/story/calendar--basic)

Each of the calendars above can be displayed with the following code.

```jsx
<Calendar calendar="islamic-civil" locale="ar" timeZone="Europe/London" />
```

:::note
Additionally the component supports a number of other calendars that are not currently used in DHIS2, since they're implemented in the [Temporal API](https://tc39.es/proposal-temporal/)). These other calendars are: `hebrew`, `islamic`, `islamic-umalqura`, `islamic-tbla`, `islamic-civil`, `islamic-rgsa`, `persian`, `ethioaa`, `coptic`, `chinese`, `dangi`, `roc`, `indian`, `buddhist`, `japanese`.
:::

## Usage

### When to use

To display a calendar for the user to pick a day in any supported calendar system, localised to any of the 90+ languages supported by [The Unicode Common Locale Data Repository (CLDR)](https://cldr.unicode.org/index) supported natively in all modern browsers. Supported DHIS2 calendars are: `iso8601` (i.e. the Gregorian calendar common in most of the world),`ethiopic`, `nepali` (custom implementation).

### When not to use

- This is just a Day Picker (for now). It does not allow picking periods, date ranges, or date with times.

## API Reference

### Calendar

#### Usage

To use `Calendar`, you can import the component from the `@dhis2/ui` library  

```js
import { Calendar } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|calendar|any||*|the calendar to use such gregory, ethiopic, nepali - full supported list here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/calendars.ts|
|onDateSelect|function||*|Called with signature `(null)` \|\| `({ dateCalendarString: string, validation: { error: boolean, warning: boolean, validationText: string} })` with `dateCalendarString` being the stringified date in the specified calendar in the format `yyyy-MM-dd`|
|cellSize|string|``'32px'``||the size of a single cell in the table forming the calendar|
|date|string|||the currently selected date using an iso-like format YYYY-MM-DD, in the calendar system provided (not iso8601)|
|dir|'ltr' │ 'rtl'|||the direction of the library - internally the library will use rtl for rtl-languages but this can be overridden here for more control|
|locale|string|||any valid locale -  if none provided, the internal library will fallback to the user locale (more info here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/hooks/internal/useResolvedLocaleOptions.ts#L15)|
|numberingSystem|string|||numbering system to use - full list here https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/numberingSystems.ts|
|pastOnly|boolean|||When true, only shows years in the past (current year and earlier)|
|timeZone|string|||the timeZone to use|
|weekDayFormat|'narrow' │ 'short' │ 'long'|``'narrow'``||the format to display for the week day, i.e. Monday (long), Mon (short), M (narrow)|
|width|string|``'240px'``||the width of the calendar component|

### CalendarInput

#### Usage

To use `CalendarInput`, you can import the component from the `@dhis2/ui` library  

```js
import { CalendarInput } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|calendar|any||*|the calendar to use such gregory, ethiopic, nepali - full supported list here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/calendars.ts|
|onDateSelect|function||*|Called with signature `(null)` \|\| `({ dateCalendarString: string, validation: { error: boolean, warning: boolean, validationText: string} })` with `dateCalendarString` being the stringified date in the specified calendar in the format `yyyy-MM-dd`|
|cellSize|string|||the size of a single cell in the table forming the calendar|
|clearable|boolean|||Whether the clear button is displayed|
|dataTest|string|||'data-test' attribute of `InputField` component|
|date|string|||the currently selected date using an iso-like format YYYY-MM-DD, in the calendar system provided (not iso8601)|
|dir|'ltr' │ 'rtl'|||the direction of the library - internally the library will use rtl for rtl-languages but this can be overridden here for more control|
|format|'YYYY-MM-DD' │ 'DD-MM-YYYY'|||The date format to use either `YYYY-MM-DD` or `DD-MM-YYYY`|
|inputWidth|string|||the width of input field|
|locale|string|||any valid locale -  if none provided, the internal library will fallback to the user locale (more info here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/hooks/internal/useResolvedLocaleOptions.ts#L15)|
|maxDate|string|||The maximum selectable date|
|minDate|string|||The minimum selectable date|
|numberingSystem|string|||numbering system to use - full list here https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/numberingSystems.ts|
|pastOnly|boolean|||When true, only shows years in the past (current year and earlier)|
|strictValidation|boolean|||Whether to use strict validation by showing errors for out-of-range dates when enabled (default), and warnings when disabled|
|weekDayFormat|'narrow' │ 'short' │ 'long'|||the format to display for the week day, i.e. Monday (long), Mon (short), M (narrow)|
|width|string|||the width of the calendar component|

## Links

- [Design document](https://docs.google.com/document/d/19zjyB45oBbqC5KeubaU8E7cw9fGhFc3tOXY0GkzZKqc/edit#)
- [ADR for decision to use Temporal API](https://github.com/dhis2/multi-calendar-dates/blob/beta/doc/architecture/decisions/0002-use-temporal-api-as-the-backbone-for-the-engine.md)
- [multi-calendar-dates](https://github.com/dhis2/multi-calendar-dates) is the library that this component is built on top of.
- [Temporal API standard propsal](https://tc39.es/proposal-temporal/): the standard powering the multi-calendar-dates library