Skip to main content
Version: 9.0.0-rc.3

Localization

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

Configure the Locale​

Prop NameTypeDescription
localeLocaleSet the locale. Default is en-US.
weekStartsOn1 | 2 | 3 | 4 | 5 | 6 | 7Display the days falling into the other months.
firstWeekContainsDate1 | 4Configure the first date in the first week of the year.
ISOWeekbooleanUse ISO Week Dates.

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
julio 2024
lumamijuvisádo
1234567
891011121314
15161718192021
22232425262728
293031

First Date of the Week​

Utilize the weekStartsOn prop to specify the starting day of the week.

<DayPicker locale={es} weekStartsOn={0} /> // Start the week on Domingo
julio 2024
dolumamijuvisá
123456
78910111213
14151617181920
21222324252627
28293031

First Week Contains Date​

The firstWeekContainsDate prop can be used to change the first day of the week for the year's initial week, which is used in the calculation of week numbers.

Acceptable values are 1 for Monday and 4 for Thursday.

<DayPicker
  showWeekNumber
  firstWeekContainsDate={1} // First week must contain Monday
/>
December 2020
SuMoTuWeThFrSa
12345
6789101112
13141516171819
20212223242526
2728293031

ISO Week Dates​

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

<DayPicker
  showWeekNumber
  ISOWeek // Switch to ISO week
/>
July 2024
MoTuWeThFrSaSu
271234567
28891011121314
2915161718192021
3022232425262728
31293031

UTC Dates​

DayPicker uses the local time zone by default. To switch to UTC dates, add @date-fns/utc to your dependencies and import DayPicker from react-day-picker/utc instead.

Experimental feature

The UTC mode is an experimental feature. Please report any issues you may encounter, thanks!

1. Install the @date-fns/utc package​

npm install @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​

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}
    />
  );
}

Observe how dates are always GMT.

July 2024
SuMoTuWeThFrSa
Sun, 07 Jul 2024 21:49:13 GMT

Translate DayPicker​

These props will assist in translating the labels and formatters utilized in DayPicker.

Prop NameTypeDescription
labelsLabelsMap the ARIA labels used within DayPicker.
formattersFormattersMap the function used as date formatters.
dirrtl | ltrSet the text direction.

ARIA Labels​

DayPicker utilizes ARIA labels to enhance screen reader accessibility. The labels prop allows for customization of these ARIA labels. For additional information, please refer to the Accessibility guide.

<DayPicker
  labels={{
    labelNext: () => "Prossimo mese"
    labelPrevious: () => "Mese precedente"
  }}
/>
FunctionDescription
labelDayThe label for the day button.
labelDayButtonThe label for the day button.
labelGridThe label for the month grid, that will be announced when entering the grid.
labelGridcellThe label for the day gridcell when the calendar is not interactive.
labelMonthDropdownThe label for the months dropdown.
labelNavThe label for the navigation toolbar, that will be announced when entering it.
labelNextThe label for next month button.
labelPreviousThe label for next month button.
labelWeekNumberThe label for the week number element.
labelWeekNumberHeaderThe label for the week number header element.
labelWeekdayThe label for the Weekday element.
labelYearDropdownThe label for the years dropdown.

RTL Text Direction​

To set the right-to-left text direction, toggle the dir prop to rtl.

import { arSA } from "date-fns/locale";

<DayPicker locale={arSA} dir="rtl" />;
يوليو 2024
أحداثنينثلاثاءأربعاءخميسجمعةسبت
123456
78910111213
14151617181920
21222324252627
28293031

Custom Formatters​

The formatters prop can be used to further format dates, week numbers, day names, and more.

<DayPicker
  formatters={{
    formatCaption: (date, options) => format(date, "LLLL yyyy", options)
  }}
/>
FunctionDescription
formatCaptionThe default formatter for the caption element.
formatDayThe default formatter for the day grid cell element.
formatMonthDropdownThe default formatter for the month dropdown value.
formatWeekNumberThe default formatter for the week numbers.
formatWeekNumberHeaderThe default formatter for the week numbers header.
formatWeekdayNameThe default formatter for the name of the weekday.
formatYearDropdownThe default formatter for the Year caption.

Numbering System​

Use the proper formatters to change the numbering system used in the calendar.

For example, to switch to hindu-arabic use the native Date.toLocaleString:

import { format } from "date-fns/format";
import { arSA } from "date-fns/locale";
import { DayPicker, Formatters } from "react-day-picker";

const NU_LOCALE = "ar-u-nu-arab";

const formatDay = (day) => day.getDate().toLocaleString(NU_LOCALE);
const formatWeekNumber = (weekNumber) => weekNumber.toLocaleString(NU_LOCALE);
const formatMonthCaption = (date, options) => {
  const y = date.getFullYear().toLocaleString(NU_LOCALE);
  const m = format(date, "LLLL", options);
  return `${m} ${y}`;
};

export function NumberingSystemExample() {
  return (
    <DayPicker
      locale={arSA}
      dir="rtl"
      showWeekNumber
      formatters={{
        formatDay,
        formatMonthCaption,
        formatWeekNumber
      }}
    />
  );
}
يوليو ٢٬٠٢٤
أحداثنينثلاثاءأربعاءخميسجمعةسبت
٢٧١٢٣٤٥٦
٢٨٧٨٩١٠١١١٢١٣
٢٩١٤١٥١٦١٧١٨١٩٢٠
٣٠٢١٢٢٢٣٢٤٢٥٢٦٢٧
٣١٢٨٢٩٣٠٣١

Jalali Calendar​

DayPicker supports the Jalali calendar thanks to 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 instead.

Experimental feature

The support for the Jalali calendar is an experimental feature. Please report any issues you may encounter, thanks!

1. Install the date-fns-jalali package​

npm install 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​

Note that you can set the right-to-left direction and change the locale.

./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شج