---
title: "Calendar Input"
description: "Calendar Input"
url: https://developers.dhis2.org/docs/ui/components/calendar-input
source: https://github.com/dhis2/developer-portal/edit/main/docs/ui/components/calendar-input.md
---

# Calendar Input

## Calendar Input

The CalendarInput is an input field with an integrated calendar picker. It combines the functionality of the [Calendar](./calendar#calendar) component with an input field, allowing users to either type a date or select one from the calendar picker.

### Demo

Below you'll find a customizable demo of the CalendarInput component. Click "show full demo" to see this and other components.

[Interactive demo: calendarinput--gregorian-with-english](https://developers.dhis2.org/demo/?path=/story/calendarinput--gregorian-with-english)

The Gregorian with initial date is then generated with this code.

```jsx
<CalendarInput
    label="Gregorian date (with initial date)"
    calendar="gregory"
    locale="en-GB"
    date="2021-10-13"
    onDateSelect={handelDateChange}
/>
```

### MinDate and MaxDate

This demo shows how to set minimum and maximum allowed dates.

[Interactive demo: calendarinput--with-min-max-date](https://developers.dhis2.org/demo/?path=/story/calendarinput--with-min-max-date)

```jsx
<CalendarInput
    label="Date with min and max"
    calendar="gregory"
    locale="en-GB"
    date="2023-06-15"
    minDate="2023-06-01"
    maxDate="2023-06-30"
    onDateSelect={handleDateChange}
/>
```

### StrictValidation

This demo demonstrates the use of strict validation for date input.

- When `strictValidation` is set to `true` (default behavior):
  The component displays error indicators if a user selects or inputs a date outside the specified minimum and maximum date range.

- When `strictValidation` is `false`:
  The component shows warning indicators for dates outside the allowed range.

[Interactive demo: calendarinput--with-strict-validation](https://developers.dhis2.org/demo/?path=/story/calendarinput--with-strict-validation)

```jsx
<CalendarInput
    label="Date with strict validation"
    calendar="gregory"
    locale="en-GB"
    strictValidation={true}
    onDateSelect={handleDateChange}
/>
```

### Format

This demo illustrates how to use the format prop to specify the date string format
The format prop accepts two possible values:

- 'YYYY-MM-DD' (default): Year-Month-Day format
- 'DD-MM-YYYY': Day-Month-Year format

[Interactive demo: calendarinput--with-custom-format](https://developers.dhis2.org/demo/?path=/story/calendarinput--with-custom-format)

```jsx
<CalendarInput
    label="Date with custom format"
    calendar="gregory"
    locale="en-GB"
    format="DD/MM/YYYY"
    onDateSelect={handleDateChange}
/>
```

### Clearable

This demo showcases the use of the `clearable` prop, which adds a button to clear the selected date.

[Interactive demo: calendarinput--with-clearable-button](https://developers.dhis2.org/demo/?path=/story/calendarinput--with-clearable-button)

```jsx
<CalendarInput
    label="Date with clear button"
    calendar="gregory"
    locale="en-GB"
    date="2023-09-25"
    clearable={true}
    onDateSelect={handleDateChange}
/>
```

### Usage

#### When to use

Use the CalendarInput component when you need to:

- Provide users with a flexible method to select a specific date, offering both manual text input and visual calendar picker.
- Implement date selection with validation, including min/max dates validation and format validation.
- Provide users with an easy way to clear a selected date.

#### When not to use

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

## 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](https://developers.dhis2.org/demo/?path=%2Fstory%2Fcalendar--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

The calendar input takes the same props as [the calendar](./calendar#calendar) component, as well as the props for [InputField](./inputfield) that are relevant to an input of type `text`.

It adds one property `clearable` which is a boolean. If set to true, it adds a clear button to delete the selected date.

### 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

- <a href="/demo/?path=/story/calendar--basic" target="_blank">Calendar Input Demo</a>
- <a href="/demo/?path=/story/calendarinput--calendar-with-editiable-input" target="_blank">Calendar Demo</a>
- [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