Hijri Calendar React DX Component for Pega Constellation

User Experience Knowledge Share
, , , , , , ,
1

HijriCalendar

A Pega Cosmos React component that provides a Hijri (Islamic) date picker with full support for both Arabic (RTL) and English (LTR) locales. Built on top of @pega/cosmos-react-core and powered by the browser’s native Intl API using the Umm al-Qura calendar.

Features

  • :date: Hijri date picker with a portal-based calendar dropdown

  • :globe_showing_europe_africa: Bilingual support — English and Arabic month/weekday labels

  • ↔️ RTL/LTR layout auto-detection

  • :floppy_disk: Flexible storage — save dates as Hijri (DD/MM/YYYY) or Gregorian ISO (YYYY-MM-DD)

  • :writing_hand: Manual text input with auto-formatting and validation

  • :bullseye: Today’s date highlighting and selected date marking

  • :tear_off_calendar: Configurable min/max Hijri year range

  • :wheelchair_symbol: Accessible — ARIA labels, roles, and keyboard support

  • :artist_palette: Fully themed using Pega Cosmos design tokens

Props

Prop Type Default Description
getPConnect () => any required PConnect object provided by Pega
value string undefined Current field value (ISO string or DD/MM/YYYY)
label string undefined Label for the input field
testId string undefined Test ID for automated testing
hideLabel boolean false Visually hides the label
minYear number 1400 Minimum selectable Hijri year
maxYear number 1500 Maximum selectable Hijri year
disabled boolean false Disables the field
readOnly boolean false Sets the field to read-only
required boolean false Marks the field as required
validatemessage string undefined Error message to display
helperText string undefined Helper text shown below the field
storeAsHijri boolean true If true, stores as DD/MM/YYYY. If false, stores as Gregorian ISO.

Date Formats

Mode Format Example
Hijri storage (storeAsHijri: true) DD/MM/YYYY 15/09/1446
Gregorian storage (storeAsHijri: false) YYYY-MM-DD 2025-03-15

The component accepts both formats as input via the value prop and will automatically convert and display the correct Hijri date.

Localization

The component automatically detects the page direction using window.getComputedStyle(document.body).direction:

  • LTR — English month names (e.g., Ramadan, Muharram) and English weekday initials

  • RTL — Arabic month names (e.g., رمضان, محرم) and Arabic weekday initials

The calendar layout and navigation arrows also flip automatically for RTL.

Calendar Navigation

  • Use the :reverse_button: / :play_button: arrow buttons to navigate between months

  • Use the month dropdown to jump directly to any Hijri month

  • Use the year dropdown to jump to any year within the configured minYear–maxYear range

  • Click any day to select it and close the calendar

Validation

  • Typing in the input field auto-formats to DD/MM/YYYY

  • Day is capped at 30, month at 12

  • If the typed year is outside the minYear–maxYear range, an inline error is shown

  • The validatemessage prop can be used to pass server-side or external validation errors

Dependencies

Package Purpose
@pega/cosmos-react-core UI components, theming, icons
styled-components Component-level CSS-in-JS styling
react-dom (createPortal) Renders calendar outside the DOM hierarchy
Intl.DateTimeFormat Native Hijri (Umm al-Qura) date conversion

Notes

  • Hijri-to-Gregorian conversion uses an approximation algorithm for calendar grid rendering. The Intl API is used for accurate Hijri date parts.

  • The calendar portal is appended to document.body to avoid overflow/clipping issues inside scrollable containers.

  • Clicking outside the calendar automatically closes it.

Document :

Hijri Calendar control.docx (283.0 KB)

GitHub Link: GitHub - sagar1567/Hijri-Calendar-DX-component · GitHub

Video Demo:

2

Thanks for contributing to the community!

Have you submitted this to Pega? We have a contribution program here.

3

Thank you for sharing the link. Will submit.

1 Like
4

Very much needed component. Thank you for contribution. Do you have maybe some demo?

Constellation 101
5

Thanks, Kamil. Added screenshot document and demo video in the post now.

6

Cool, thank you pinned to Constellation 101. I will be also advertising on LinkedIn so broader audience can see it. Remember doing Constellation bootcamp in Riyadh, Hijri calendar component was one of most frequent topics.

1 Like
7

Constellation 101 Series

Enjoyed this article? See more similar articles in Constellation 101 series.