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.

The maintained packages share version 1.0.0. If you used the older taqwim-core-utils or taqwim-vue packages, follow the 1.0 migration guide before changing your imports.

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 Jumada 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 Jumada 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 Jumada 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 Jumada 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.

This documentation page does not embed an Angular calendar. The playground/angular app runs in the shared browser suite with the other four frameworks.

The adapter and playground also build with Angular's strictTemplates checks.

Install

pnpm add @taqwim/vue-styled

pnpm add @taqwim/react-styled

pnpm add @taqwim/svelte-styled

pnpm add @taqwim/solid-styled

pnpm add @taqwim/angular-styled

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, type HijriCalendarProps } from '@taqwim/vue-styled'
import { ref } from 'vue'

const date = ref<HijriCalendarProps['modelValue']>()
</script>

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

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

export function Example() {
  const [date, setDate] = useState<HijriCalendarProps['value']>()

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

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

  let date = $state<HijriCalendarProps['value']>()
</script>

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

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

export function Example() {
  const [date, setDate] = createSignal<HijriCalendarProps['value']>()

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

import { HijriCalendar, type HijriCalendarInputs } 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<HijriCalendarInputs['value']>(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

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

// Vue:    <HijriCalendar :calendar-system="islamicCivil" />
// React, Svelte, Solid: <HijriCalendar calendarSystem={islamicCivil} />
// Angular: <taqwim-hijri-calendar [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

This documentation page does not embed an Angular date picker. The playground/angular app includes the date picker and its Hijri calendar switch. The shared Playwright suite exercises them in the browser, and Angular's strict template checks run during the build.

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

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

const today = toHijri(new Date()) // The current local date in Hijri fields.
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.