Localization

Learn how to set the locale, changing the time zone, and adjust other calendar options.

Setting the Locale

Prop Name	Type	Description
locale	Locale	Set the locale. Default is en-US.

DayPicker export the date-fns locales for easier calendar localization. To set a different locale, import it from react-day-picker/locale.

// import the locale object
import { es } from "react-day-picker/locale";

By default, the locale is set to English (US). To localize the calendar, pass the imported Locale object to the locale prop.

For example, to localize the calendar in Spanish, import the es locale object from date-fns and pass it to the component.

import { es } from "react-day-picker/locale";

<DayPicker locale={es} />; // Set the locale to Spanish

septiembre 2024

lu	ma	mi	ju	vi	sá	do
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30	1	2	3	4	5	6

Customizing the Locale

You can customize the locale by passing an object with the desired translations. Use the defaultLocale object for the default translation values.

import { DayPicker, defaultLocale } from "react-day-picker";

<DayPicker
  locale={{
    localize: {
      ...defaultLocale.localize,
      day: (day) => "custom-localized-day"
    }
  }}
  month={new Date(2023, 0, 1)}
  mode="single"
/>;

Changing the Time Zone

Experimental Feature

Time zones are supported by the TZDate object by the @date-fns/tz package. If you encounter any issues, please report them. Thank you!

Prop Name	Type	Description
timeZone	string	Set a time zone for the dates in the calendar.

Use the timeZone prop to set a different time zone for the calendar. See Wikipedia for a list of the possible values.

<DayPicker timeZone="UTC" /> // Use Coordinated Universal Time
<DayPicker timeZone="Pacific/Kiritimati" /> // Use Line Islands Time

September 2024

Su	Mo	Tu	We	Th	Fr	Sa

Fri Sep 20 2024 03:50:24 GMT+1400 (Line Islands Time)

Working with Time-Zoned Dates

When working with time zones, make sure to use the TZDate object instead of the native Date object. The TZDate object is exported from @date-fns/tz. Refer to their documentation for more information.

To initialize a date in a specific time zone, use the tz method:

export function TimeZone() {
  const timeZone = "America/New_York";
  const [selected, setSelected] = useState<Date | undefined>(
    TZDate.tz(timeZone) // Make sure you use `TZDate` instead of `Date`
  );
  return (
    <DayPicker
      mode="single"
      timeZone={timeZone}
      selected={selected}
      onSelect={setSelected}
    />
  );
}

Calendar Options

Prop Name	Type	Description
weekStartsOn	1 | 2 | 3 | 4 | 5 | 6 | 7	Display the days falling into the other months.
firstWeekContainsDate	1 | 4	Configure the first date in the first week of the year.
ISOWeek	boolean	Use ISO Week Dates.

First Date of the Week

Use the weekStartsOn prop to set the first day of the week.

<DayPicker locale={es} weekStartsOn={0} /> // Start the week on Domingo

septiembre 2024

do	lu	ma	mi	ju	vi	sá
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30	1	2	3	4	5

First Week Contains Date

The firstWeekContainsDate prop sets the first day of the year's initial week, which is used to calculate week numbers.

• Acceptable values are 1 for Monday and 4 for Thursday.
• For more information, see Week Numbering and the getWeek function.

<DayPicker
  showWeekNumber
  firstWeekContainsDate={1} // First week must contain Monday
/>

ISO Week Dates

Use the ISOWeek prop to switch to ISO Week Dates instead of the locale setting.

<DayPicker ISOWeek />

September 2024

	Mo	Tu	We	Th	Fr	Sa	Su
35	26	27	28	29	30	31	1
36	2	3	4	5	6	7	8
37	9	10	11	12	13	14	15
38	16	17	18	19	20	21	22
39	23	24	25	26	27	28	29
40	30	1	2	3	4	5	6

Jalali Calendar

DayPicker supports the Jalali calendar through the date-fns-jalali package. To switch to the Jalali calendar, add date-fns-jalali to your dependencies and import DayPicker from react-day-picker/jalali.

Experimental Feature

Support for the Jalali calendar is an experimental feature. Please report any issues you encounter. Thank you!

1. Install the date-fns-jalali package

npm

npm install date-fns-jalali

Yarn

yarn add date-fns-jalali

pnpm

pnpm add date-fns-jalali

2. Import DayPicker from react-day-picker/jalali

- import { DayPicker } from 'react-day-picker';
+ import { DayPicker } from 'react-day-picker/jalali';

3. Use DayPicker as usual

You can set the right-to-left direction and change the locale as needed.

./JalaliCalendar.jsx

import React from "react";

import { DayPicker } from "react-day-picker/jalali";
import { faIR } from "react-day-picker/locale";

export function Jalali() {
  return <DayPicker mode="single" locale={faIR} dir="rtl" />;
}

جون 1403

ش	1ش	2ش	3ش	4ش	5ش	ج