date-fns-hijri/.github/wiki/examples/formatting.md

Formatting Examples

All examples use formatHijriDate. The function takes a Gregorian Date, a format string with Hijri tokens, and an optional options argument for calendar selection.

Token reference

Token	Output example	Description
iYYYY	1444	Hijri year, 4 digits
iYY	44	Hijri year, 2 digits
iMM	09	Month number, zero-padded
iM	9	Month number, unpadded
iMMMM	Ramadan	Full month name
iMMM	Ram	3-letter month abbreviation
iDD	01	Day of month, zero-padded
iD	1	Day of month, unpadded

Common formats

import { formatHijriDate } from 'date-fns-hijri';

// 1 Ramadan 1444 CE = March 23, 2023 CE
const date = new Date(2023, 2, 23);

// Numeric ISO-style (useful for sorting)
formatHijriDate(date, 'iYYYY-iMM-iDD');
// '1444-09-01'

// Numeric short
formatHijriDate(date, 'iDD/iMM/iYYYY');
// '01/09/1444'

// Long form
formatHijriDate(date, 'iD iMMMM iYYYY');
// '1 Ramadan 1444'

// With abbreviation
formatHijriDate(date, 'iD iMMM iYY AH');
// '1 Ram 44 AH'

// Arabic-script label (month name only changes)
formatHijriDate(date, 'iDD iMMMM iYYYY');
// '01 Ramadan 1444'

Mixing Hijri tokens with literal text

Literal text passes through unchanged. Wrap text in single quotes if it contains characters that could be interpreted as format tokens.

// 'AH' contains 'A' and 'H' which are not Hijri tokens, so this is safe
formatHijriDate(date, 'iD iMMMM iYYYY AH');
// '1 Ramadan 1444 AH'

// Single-quote wrapping for safety
formatHijriDate(date, "iD 'of' iMMMM, iYYYY");
// '1 of Ramadan, 1444'

FCNA calendar formatting

import { formatHijriDate } from 'date-fns-hijri';

const date = new Date(2023, 2, 23);
const fcna = { calendar: 'fcna' };

formatHijriDate(date, 'iD iMMMM iYYYY', fcna);
// May be '1 Ramadan 1444' or '2 Ramadan 1444' depending on the astronomical calculation

Formatting in a React component

import { formatHijriDate } from 'date-fns-hijri';

function HijriDisplay({ date }: { date: Date }) {
  return (
    <span className="hijri-date">
      {formatHijriDate(date, 'iD iMMMM iYYYY')}
    </span>
  );
}

Generating a Hijri calendar grid header

import { getHijriMonthName } from 'date-fns-hijri';

// Render all 12 month names for a year selector
const months = Array.from({ length: 12 }, (_, i) => ({
  number: i + 1,
  name: getHijriMonthName(i + 1),
  short: getHijriMonthName(i + 1, { format: 'short' }),
}));