# Hijri dates

> Convert between Gregorian and Hijri (Islamic) dates with the tabular calendar, name Hijri months and check for Ramadan, with a day offset for moon sighting.

Source: https://pakdatakit.dev/docs/hijri/

`import { toHijri, fromHijri, formatHijri, getHijriMonthName, isRamadan } from 'pakdatakit/hijri'`

Converts Gregorian dates to Hijri (Islamic) dates and back, formats them as `"12 Ramadan 1447"`, and tells whether a date falls in Ramadan. Everything works offline from arithmetic, with no table of dates.

> **The tabular calendar, not moon sighting**
>
> The conversion uses the tabular (arithmetic, "islamic-civil") calendar. Actual dates in Pakistan follow moon sighting and can differ by a day or two. Pass `offset` to adjust, for example `-1` when Pakistan's Ruet-e-Hilal calendar runs a day behind the tabular date.
## Examples

**TypeScript**

```ts
import { formatHijri, toHijri, fromHijri, isRamadan } from 'pakdatakit';

formatHijri(new Date(2026, 2, 1, 0, 0));
// → '12 Ramadan 1447'

toHijri(new Date(2026, 2, 1, 0, 0));
// → {
//     "year": 1447,
//     "month": 9,
//     "day": 12
//   }

fromHijri({
  year: 1447,
  month: 9,
  day: 1,
});
// → 2026-02-18 (a date)

isRamadan(new Date(2026, 2, 1, 0, 0));
// → true
```

**Python**

```python
from datetime import datetime
from pakdatakit import format_hijri, to_hijri, from_hijri, is_ramadan

format_hijri(datetime(2026, 3, 1, 0, 0))
# → '12 Ramadan 1447'

to_hijri(datetime(2026, 3, 1, 0, 0))
# → {
#     "year": 1447,
#     "month": 9,
#     "day": 12
#   }

from_hijri({
  'year': 1447,
  'month': 9,
  'day': 1,
})
# → 2026-02-18 (a date)

is_ramadan(datetime(2026, 3, 1, 0, 0))
# → True
```

**Dart**

```dart
import 'package:pakdatakit/pakdatakit.dart';

formatHijri(DateTime(2026, 3, 1, 0, 0));
// → '12 Ramadan 1447'

toHijri(DateTime(2026, 3, 1, 0, 0));
// → {
//     "year": 1447,
//     "month": 9,
//     "day": 12
//   }

fromHijri(HijriDate(year: 1447, month: 9, day: 1));
// → 2026-02-18 (a date)

isRamadan(DateTime(2026, 3, 1, 0, 0));
// → true
```

**C#**

```csharp
using PakDataKit;

Hijri.Format(new DateOnly(2026, 3, 1));
// → "12 Ramadan 1447"

Hijri.ToHijri(new DateOnly(2026, 3, 1));
// → {
//     "year": 1447,
//     "month": 9,
//     "day": 12
//   }

Hijri.FromHijri(new HijriDate(1447, 9, 1));
// → 2026-02-18 (a date)

Hijri.IsRamadan(new DateOnly(2026, 3, 1));
// → true
```

**PHP**

```php
use PakDataKit\Hijri;
use PakDataKit\HijriDate;

Hijri::format(new DateTimeImmutable('2026-03-01 00:00:00'));
// → '12 Ramadan 1447'

Hijri::toHijri(new DateTimeImmutable('2026-03-01 00:00:00'));
// → {
//     "year": 1447,
//     "month": 9,
//     "day": 12
//   }

Hijri::fromHijri(new HijriDate(1447, 9, 1));
// → 2026-02-18 (a date)

Hijri::isRamadan(new DateTimeImmutable('2026-03-01 00:00:00'));
// → true
```

## Reference

### toHijri()

```ts
function toHijri(date: Date, options?: HijriOptions): HijriDate;

interface HijriDate {
  year: number;
  month: number; // 1 to 12
  day: number;
}

interface HijriOptions {
  offset?: number; // whole days, default 0
}
```

**Parameters.** `date`: a Gregorian date; its local date (year, month, day) is used. `options.offset`: whole days to shift the tabular calendar by, to match local moon sighting.

**Returns** the Hijri year, month and day.

**Caveats.** Throws a `RangeError` if `date` is invalid or `offset` is not an integer.

**Related:** [`formatHijri()`](#formathijri), [`fromHijri()`](#fromhijri).

### fromHijri()

```ts
function fromHijri(hijri: HijriDate, options?: HijriOptions): Date;
```

**Parameters.** `hijri`: the Hijri year, month and day. `options.offset`: the same offset used with [`toHijri()`](#tohijri).

**Returns** the Gregorian date, at local midnight.

**Caveats.** Throws a `RangeError` if the Hijri parts are out of range: the year must be 1 or more, the month 1 to 12 and the day 1 to 30.

### formatHijri()

```ts
function formatHijri(date: Date, options?: HijriOptions): string;
```

**Returns** the Hijri date as a string, such as `"14 Ramadan 1447"`: the day, the English month name and the year.

**Related:** [`getHijriMonthName()`](#gethijrimonthname).

### getHijriMonthName()

```ts
function getHijriMonthName(month: number): string | null;
```

**Returns** the English name of a Hijri month (1 to 12): Muharram, Safar, Rabi al-Awwal, Rabi al-Thani, Jumada al-Awwal, Jumada al-Thani, Rajab, Shaaban, Ramadan, Shawwal, Dhu al-Qadah, Dhu al-Hijjah. Returns `null` if `month` is not an integer from 1 to 12.

### isRamadan()

```ts
function isRamadan(date: Date, options?: HijriOptions): boolean;
```

**Returns** `true` when the date falls in Ramadan, the ninth Hijri month.

**Caveats.** As for every function here, the start and end of Ramadan follow the tabular calendar unless you pass an `offset`; the announced dates can differ by a day or two.

**Related:** [public holidays](https://pakdatakit.dev/docs/holidays/) for Eid dates actually observed in Pakistan.

## Related

- [TypeScript API reference for `pakdatakit/hijri`](https://pakdatakit.dev/api/typescript/hijri/)
- [Public holidays](https://pakdatakit.dev/docs/holidays/)
