Skip to main content

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​

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, dateCalendar: Temporal.ZonedDateTime }) 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'