Hijri Date
View on StorybookStorybookA beautiful component to display both Gregorian and Hijri (Islamic calendar) dates together. Designed for Islamic and Arabic-speaking contexts with full bilingual support and multiple layout variants.
Preview
Installation
Copy and paste the component code into your project:
Dependencies: This component uses Phosphor icons which should already be installed in your project.
Usage
Examples
Default
Card-style layout with labels, perfect for prominent date displays.
Badge
Compact inline badge, great for headers or metadata sections.
Compact
Minimal inline text, perfect for content flows and timestamps.
Detailed
Large, spacious layout with enhanced typography for feature sections.
In Content
Multiple variants used together in a card layout.
Event Details
Integration with Date Conversion Libraries
This component is UI-only and accepts pre-formatted date strings. You can integrate it with Hijri calendar conversion libraries. Here's an example using @formkit/hijri:
Install the library: npm install @formkit/hijri
Props
| Name | Type | Default | Description |
|---|---|---|---|
gregorianDateRequired | string | — | Gregorian date in English (e.g., "November 6, 2025"). |
gregorianDateAr | string | undefined | Gregorian date in Arabic (optional, displayed in RTL mode if provided). |
hijriDateRequired | string | — | Hijri date in English (e.g., "5 Jumada al-Awwal 1447"). |
hijriDateArRequired | string | — | Hijri date in Arabic (e.g., "٥ جمادى الأولى ١٤٤٧"). |
showIcon | boolean | false | Display a calendar icon with the dates. |
variant | "default" | "badge" | "compact" | "detailed" | "default" | Visual variant controlling layout and styling. |
className | string | undefined | Additional CSS classes for the wrapper element. |
Accessibility
The Hijri Date component follows accessibility best practices:
- Semantic HTML: Uses proper semantic elements for date display.
- Clear Labels: Date type labels ("Gregorian", "Hijri") provide context.
- Visual Hierarchy: Consistent styling helps distinguish between date types.
- Separator: Visual bullet separator in inline variants is marked with aria-hidden.
- Readable Typography: Font sizes and weights optimized for readability.
RTL Considerations
This component is built with RTL-first principles and automatically adapts to text direction:
- Automatic Language Detection: Displays Arabic dates (gregorianDateAr, hijriDateAr) in RTL mode.
- Logical Properties: Uses margin-inline-start (ms-*) and gap for proper spacing.
- Flexible Layout: All variants adapt seamlessly to both LTR and RTL directions.
- Icon Positioning: Calendar icon positions correctly in both directions.
- Text Alignment: Date labels and values align naturally based on direction.
Use Cases
Islamic calendar date displays
Dual calendar date pickers
Religious event date references
Government document date headers
Best Practices
Do
- ✓ Show both Hijri and Gregorian dates when relevant
- ✓ Use the correct month names in Arabic
- ✓ Support Umm al-Qura calendar for Saudi contexts
Don't
- ✗ Don't assume one-to-one month mapping between calendars
- ✗ Don't use Western numerals for Hijri dates in Arabic context
- ✗ Don't omit the calendar system indicator