Getting started

Taqwim is a set of packages, not one. Pick the pair that matches your framework: a headless package for behaviour and accessibility, and a styled package if you want it to look like a calendar out of the box.

This is the real component from the real package — the same one the code below installs. The buttons above the page switch every example on it, this one included.

Theme Hijri calendar Size Language Text direction Select multiple dates Show Gregorian date Emphasize

Calendar for Rabi' al-awwal 1448

Selectednothing yet

Tab into the grid, then use the arrow keys, Home/End, PageUp/PageDown (with Shift for years) and Enter to select. Under dir="rtl" the horizontal keys mirror.

ThemeHijri calendarSizeLanguageText direction Select multiple dates Show Gregorian dateEmphasize

Calendar for Rabi' al-awwal 1448

Selectednothing yet

Tab into the grid, then use the arrow keys, Home/End, PageUp/PageDown (with Shift for years) and Enter to select. Under dir="rtl" the horizontal keys mirror.

Theme Hijri calendar Size Language Text direction Select multiple dates Show Gregorian date Emphasize

Calendar for Rabi' al-awwal 1448

Selected nothing yet

Tab into the grid, then use the arrow keys, Home/End, PageUp/PageDown (with Shift for years) and Enter to select. Under dir="rtl" the horizontal keys mirror.

ThemeHijri calendarSizeLanguageText direction Select multiple dates Show Gregorian dateEmphasize

Calendar for Rabi' al-awwal 1448

Selectednothing yet

Tab into the grid, then use the arrow keys, Home/End, PageUp/PageDown (with Shift for years) and Enter to select. Under dir="rtl" the horizontal keys mirror.

No live Angular island here. @analogjs/vite-plugin-angular does not compile an Angular app under Vite 8, which is the same gap that keeps Angular out of the default end-to-end run.

The adapter and playground/angular source — including the same Hijri calendar switch — are built and type-checked by ngc with strictTemplates on every change.

Install

pnpm add @taqwim/vue-styled@beta

pnpm add @taqwim/react-styled@beta

pnpm add @taqwim/svelte-styled@beta

pnpm add @taqwim/solid-styled@beta

pnpm add @taqwim/angular-styled@beta

Each styled package pulls in its headless sibling and @taqwim/themes, so that is the only dependency you need to add.

Render a calendar

<script setup lang="ts">
import { HijriCalendar } from '@taqwim/vue-styled'
import { ref } from 'vue'

const date = ref()
</script>

<template>
  <HijriCalendar v-model="date" theme="islamic" locale="ar" dir="rtl" />
</template>

import { HijriCalendar } from '@taqwim/react-styled'
import { useState } from 'react'

export function Example() {
  const [date, setDate] = useState()

  return <HijriCalendar value={date} onValueChange={setDate} theme="islamic" locale="ar" dir="rtl" />
}

<script lang="ts">
  import { HijriCalendar } from '@taqwim/svelte-styled'

  let date = $state()
</script>

<HijriCalendar value={date} onValueChange={next => (date = next)} theme="islamic" locale="ar" dir="rtl" />

import { HijriCalendar } from '@taqwim/solid-styled'
import { createSignal } from 'solid-js'

export function Example() {
  const [date, setDate] = createSignal()

  return <HijriCalendar value={date()} onValueChange={setDate} theme="islamic" locale="ar" dir="rtl" />
}

import { HijriCalendar } from '@taqwim/angular-styled'
import { Component, signal } from '@angular/core'

@Component({
  standalone: true,
  imports: [HijriCalendar],
  template: `
    <taqwim-hijri-calendar [value]="date()" (valueChange)="date.set($event)" theme="islamic" locale="ar" dir="rtl" />
  `,
})
export class Example {
  readonly date = signal(undefined)
}

Choose a Hijri calendar system

Every calendar uses Umm al-Qura by default. To use Islamic Civil or Islamic TBLA, add @taqwim/core directly, import the strategy, and pass it through the same calendarSystem option in every framework:

pnpm add @taqwim/core@beta

import { islamicCivil } from '@taqwim/core/calendars/islamic-civil'

// Vue:    <HijriCalendar :calendar-system="islamicCivil" />
// Others: <HijriCalendar calendarSystem={islamicCivil} />

Hijri calendar systems compares Umm al-Qura, Islamic Civil and Islamic TBLA, including their ranges, epoch rules, imports and storage implications.

The date picker

HijriDatePicker is the same calendar behind a text input. It is single-select by design: the input holds one formatted date. Previous and next page the month; the heading is two buttons — month and year — each opening its own picker.

Hijri calendar Date format Language Allow typing Show Gregorian date Emphasize Input shows

Selectednothing yet

With editable on, the input accepts 1446-09-01 or 01/09/1446. Text it cannot parse reverts to the last good value rather than clearing the selection. The trigger is a combobox: Enter opens the popup, Escape closes it and returns focus.

Hijri calendarDate formatLanguage Allow typing Show Gregorian dateEmphasizeInput shows

Selectednothing yet

Hijri calendar Date format Language Allow typing Show Gregorian date Emphasize Input shows

Selected nothing yet

Hijri calendarDate formatLanguage Allow typing Show Gregorian dateEmphasizeInput shows

Selectednothing yet

No live Angular island here — @analogjs/vite-plugin-angular does not compile an Angular app under Vite 8. The playground/angular source includes the date picker and its Hijri calendar switch, and both are covered by Angular's strict template checks.

Just the date maths

If you only need conversion and arithmetic — on a server, say — @taqwim/core has no framework dependency and no DOM.

pnpm add @taqwim/core@beta

import { toHijri, toGregorian, addHijriMonths, formatHijriDate } from '@taqwim/core'

const today = toHijri(new Date()) // { hy: 1447, hm: 2, hd: 14 }
const later = addHijriMonths(today, 3)

formatHijriDate(later, 'iD iMMMM iYYYY', 'ar')
toGregorian(later) // a Date at local midnight

Default Umm al-Qura conversion covers 1343–1500 AH (1924–2077 CE), the range its table defines. Outside it, Taqwim throws HijriRangeError rather than returning a quietly wrong date. Islamic Civil and Islamic TBLA are proleptic arithmetic alternatives; see Hijri calendar systems.

Dates without a calendar covers the rest of that package: arithmetic, business days, comparison, parsing and locale-aware formatting.

Build your own markup

The styled packages are composed entirely from public headless parts. When you need different markup, drop to those — see your framework’s page under Frameworks for the full compound surface.