mantine-datepicker-persian

Jalali (Persian / Shamsi) date and time pickers for Mantine v9.

Drop-in replacement for @mantine/dates with Persian calendar support. Same API as @mantine/[email protected] — swap the import and set locale="fa".

npm i mantine-datepicker-persian @mantine/core @mantine/hooks dayjs

Package name on npm: mantine-datepicker-persian
Repo: samirarezai/mantine-datepicker-jalali

Why this package?

@mantine/dates only supports Gregorian calendars. This package forks it and adds Jalali rendering when the locale is fa / fa-IR:

| | @mantine/dates | mantine-datepicker-persian | | --- | --- | --- | | Gregorian | Yes | Yes | | Jalali (Persian) | No | Yes (locale="fa") | | Mantine version | 9.x | 9.x | | Value type | YYYY-MM-DD strings | Same |

Do not install both. Use this package instead of @mantine/dates.

Requirements

| Peer dependency | Version | | --- | --- | | @mantine/core | >=9 <10 | | @mantine/hooks | >=9 <10 | | dayjs | >=1.11 <2 | | react / react-dom | >=19 <20 |

Setup

1. Install

npm i mantine-datepicker-persian @mantine/core @mantine/hooks dayjs

2. Import CSS (once, in your app root)

import '@mantine/core/styles.css';
import 'mantine-datepicker-persian/styles.css';
import 'dayjs/locale/fa';

Optional CSS layer variant (if you use Mantine layers):

import 'mantine-datepicker-persian/styles.layer.css';

3. Wrap your app

import { DirectionProvider, MantineProvider } from '@mantine/core';
import { DatesProvider } from 'mantine-datepicker-persian';

export function App({ children }: { children: React.ReactNode }) {
  return (
    <DirectionProvider initialDirection="rtl">
      <MantineProvider>
        <DatesProvider
          settings={{
            locale: 'fa',
            firstDayOfWeek: 6, // Saturday
            weekendDays: [5], // Friday
          }}
        >
          {children}
        </DatesProvider>
      </MantineProvider>
    </DirectionProvider>
  );
}

| Setting | Persian calendar recommendation | | --- | --- | | locale | 'fa' | | firstDayOfWeek | 6 (Saturday) | | weekendDays | [5] (Friday) | | Direction | RTL via DirectionProvider |

Date values

Values are strings, not Date objects (same as Mantine Dates 8+):

| Component | Value shape | Example | | --- | --- | --- | | Date (default) | string \| null | '2024-03-20' | | Date + time | string \| null | '2024-03-20 14:30:00' | | Multiple | string[] | ['2024-03-20', '2024-03-21'] | | Range | [string \| null, string \| null] | ['2024-03-20', '2024-03-25'] |

The stored value is always Gregorian ISO (YYYY-MM-DD). The UI shows Jalali when locale="fa".

Components

DateInput — typeable input + calendar

import { useState } from 'react';
import { DateInput, DateValue } from 'mantine-datepicker-persian';

function Example() {
  const [value, setValue] = useState<DateValue>(null);

  return (
    <DateInput
      label="تاریخ"
      placeholder="تاریخ را وارد کنید"
      value={value}
      onChange={setValue}
      locale="fa"
      clearable
    />
  );
}

DatePickerInput — input that opens a calendar dropdown

import { DatePickerInput } from 'mantine-datepicker-persian';

<DatePickerInput
  label="تاریخ"
  value={value}
  onChange={setValue}
  locale="fa"
  clearable
/>

DateTimePicker — date + time

import { DateTimePicker } from 'mantine-datepicker-persian';

<DateTimePicker
  label="تاریخ و زمان"
  value={dateTime}
  onChange={setDateTime}
  locale="fa"
  clearable
  valueFormat="YYYY/MM/DD HH:mm"
/>

valueFormat tokens (YYYY, MM, DD, HH, mm, …) are rendered in Jalali when locale="fa".

DatePicker — inline calendar

Single

<DatePicker value={value} onChange={setValue} locale="fa" />

Multiple

const [dates, setDates] = useState<string[]>([]);

<DatePicker
  type="multiple"
  value={dates}
  onChange={setDates}
  locale="fa"
  firstDayOfWeek={6}
  weekendDays={[5]}
/>

Range

const [range, setRange] = useState<[string | null, string | null]>([null, null]);

<DatePicker
  type="range"
  value={range}
  onChange={setRange}
  locale="fa"
  firstDayOfWeek={6}
  weekendDays={[5]}
/>

Also included

Same surface as @mantine/dates:

• MonthPicker / MonthPickerInput
• YearPicker / YearPickerInput
• TimePicker / TimeInput / TimeGrid
• InlineDateTimePicker
• MiniCalendar
• Calendar, DatesProvider, …

Migrating from @mantine/dates

- import { DateInput, DatesProvider } from '@mantine/dates';
- import '@mantine/dates/styles.css';
+ import { DateInput, DatesProvider } from 'mantine-datepicker-persian';
+ import 'mantine-datepicker-persian/styles.css';

1. Uninstall @mantine/dates
2. Install mantine-datepicker-persian
3. Replace imports and CSS path
4. Set locale="fa" (component prop and/or DatesProvider)

Props and behavior match @mantine/dates 9.x. Jalali mode activates only for fa / fa-IR.

Jalali behavior notes

• Display uses the Persian calendar (month names, day numbers, year).
• Stored values stay Gregorian YYYY-MM-DD so APIs and databases keep working.
• Time fields stay LTR (HH:mm) even inside RTL layouts.
• Persian digits in time inputs are accepted and normalized.

License

MIT