Skip to main content

Calendar Input

Calendar Input​

The CalendarInput is an input field with an integrated calendar picker. It combines the functionality of the 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.

Demo

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

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

Demo
<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.

Demo
<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
Demo
<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.

Demo
<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 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. 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 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​

Demo

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.

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

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

Nepali calendar transliterated into latin characters.

Demo
// 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.

Demo

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

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

Other calendars​

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

Demo

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

<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). 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) 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 component, as well as the props for 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

import { Calendar } from '@dhis2/ui'

Props​

NameTypeDefaultRequiredDescription
calendarany*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
onDateSelectfunction*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
cellSizestring'32px'the size of a single cell in the table forming the calendar
datestringthe 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
localestringany 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)
numberingSystemstringnumbering system to use - full list here https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/numberingSystems.ts
timeZonestringthe timeZone to use
weekDayFormat'narrow' │ 'short' │ 'long''narrow'the format to display for the week day, i.e. Monday (long), Mon (short), M (narrow)
widthstring'240px'the width of the calendar component

CalendarInput​

Usage​

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

import { CalendarInput } from '@dhis2/ui'

Props​

NameTypeDefaultRequiredDescription
calendarany*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
onDateSelectfunction*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
cellSizestringthe size of a single cell in the table forming the calendar
clearablebooleanWhether the clear button is displayed
dataTeststring'data-test' attribute of InputField component
datestringthe 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
inputWidthstringthe width of input field
localestringany 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)
maxDatestringThe maximum selectable date
minDatestringThe minimum selectable date
numberingSystemstringnumbering system to use - full list here https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/numberingSystems.ts
strictValidationbooleanWhether 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)
widthstringthe width of the calendar component