jalali-js

English

فارسی

English

فارسی

Appearance

Documentation / @jalali-js/react

@jalali-js/react ​

npm versionLicense: MITDocs

React bindings for jalali-js: useCalendar, headless Calendar, styled DatePicker and TimePicker, and SSR-safe timezone resolution.

Start here: Live demo · Documentation

npm ecosystem: jalali-js · @jalali-js/i18n · @jalali-js/nlp · @jalali-js/holidays · @jalali-js/react · @jalali-js/vue · @jalali-js/web · @jalali-js/ui-react · @jalali-js/ui-vue · @jalali-js/ui-web

Contents ​

Install ​

sh
npm install @jalali-js/react

Import the default stylesheet once for the styled pickers:

ts
import '@jalali-js/react/date-picker.css';

Compatibility ​

ItemSupport
React18 and 19 (CI matrix)
Next.js15 and 16 (CI matrix). Use client components
Peersreact and react-dom >=18
Node22 and 24 (CI matrix)

Quick start ​

tsx
import '@jalali-js/react/date-picker.css';
import { DatePicker } from '@jalali-js/react';

<DatePicker
  system="jalali"
  locale="fa"
  onChange={(value, date) => {
    // value: Gregorian ISO by default; date: CalendarDate
  }}
/>;

Components ​

DatePicker ​

Styled input plus popover grid (default), or variant="dropdown" year/month/day selects. Set precision="datetime" for a time panel. Emits a storage value through onChange.

Calendar ​

Headless month grid (data-jalali-* attributes, no required CSS). Use it for an always-visible calendar or your own chrome around the grid.

TimePicker ​

Hour and minute lists (minuteStep, disabledHours).

useCalendar / useResolvedTimeZone ​

  • useCalendar({ system, locale, initialDate? }) for format helpers and today.
  • useResolvedTimeZone() with precision: 'zoned-datetime' and timeZone: 'auto' under Next.js SSR (server and first client render stay UTC, then the real zone mounts cleanly).

Range, inline, event, and time-range UIs live in @jalali-js/ui-react.

Options ​

Key DatePicker props:

PropTypeDefaultNotes
system'jalali' | 'gregorian''jalali'Display calendar
locale'en' | 'fa' | 'ps''en'UI language
valueFormatValueFormat'gregorian-iso'Stored onChange value shape
variant'grid' | 'dropdown''grid'Popover grid or Y/M/D selects
precision'date' | 'datetime''date'Add a time panel
rulesSelectionRules-Min/max and blocked days
showHolidaysbooleanfalseNeeds @jalali-js/holidays

Full tables: React guide.

Theming ​

Override CSS variables on a parent (or the root):

css
[data-jalali-datepicker-root] {
  --jalali-primary: #2563eb;
  --jalali-radius: 8px;
  --jalali-bg: #ffffff;
  --jalali-fg: #1a1a1a;
}

See Theming.

License ​

MIT

Interfaces ​

Type Aliases ​

Functions ​