Localization

Learn how to set the locale, adjust the starting day of the week, and apply ISO Week Dates to enhance the user experience across different regions and languages.

Locale props

Prop Name	Type	Description
locale	Locale	Set the locale. Default is en-US.
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.

Setting the Locale

1. Install date-fns

DayPicker uses the date-fns library for calendar localization. To set a different locale, install date-fns:

npm

npm install date-fns

Yarn

yarn add date-fns

pnpm

pnpm add date-fns

2. Set a Different Locale

By default, the locale is set to English (US). To localize the calendar, pass a 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 "date-fns/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"
/>;

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

UTC Dates

Since DayPicker works with the native JavaScript Date, it uses the local time zone by default. To switch to UTC dates:

1. Add @date-fns/utc to your dependencies.
2. Import DayPicker from react-day-picker/utc.
3. Use new UTCDate() instead of new Date().

Experimental feature

The UTC mode is an experimental feature. If you encounter any issues, please report them. Thank you!

1. Install the @date-fns/utc package

npm

npm install @date-fns/utc

Yarn

yarn add @date-fns/utc

pnpm

pnpm add @date-fns/utc

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

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

3. Use DayPicker as usual

Use new UTCDate() instead of new Date() to ensure dates are always in GMT.

import { UTCDate } from "@date-fns/utc";
import { DayPicker } from "react-day-picker/utc";

export function Utc() {
  const [selected, setSelected] = React.useState<Date>(new UTCDate());
  return (
    <DayPicker
      mode="single"
      required
      selected={selected}
      onSelect={(date: Date) => {
        setSelected(date);
      }}
      footer={selected ? `Selected: ${selected.toUTCString()}` : null}
    />
  );
}

September 2024

Su	Mo	Tu	We	Th	Fr	Sa

Tue, 10 Sep 2024 11:05:28 GMT

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 { faIR } from "date-fns/locale";
import { DayPicker } from "react-day-picker/jalali";

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

جون 1403

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