Skip to main content
The LocaleConfig object is used to configure calendar localization. It’s built on XDate’s localization system and allows you to customize month names, day names, and other locale-specific settings.

​
Import

import { LocaleConfig } from 'react-native-calendars';
LocaleConfig is a global configuration object. Changes affect all calendar components in your application.

​
Basic usage

import { LocaleConfig } from 'react-native-calendars';

// Configure French locale
LocaleConfig.locales['fr'] = {
  monthNames: [
    'Janvier',
    'Février',
    'Mars',
    'Avril',
    'Mai',
    'Juin',
    'Juillet',
    'Août',
    'Septembre',
    'Octobre',
    'Novembre',
    'Décembre'
  ],
  monthNamesShort: [
    'Janv.',
    'Févr.',
    'Mars',
    'Avril',
    'Mai',
    'Juin',
    'Juil.',
    'Août',
    'Sept.',
    'Oct.',
    'Nov.',
    'Déc.'
  ],
  dayNames: [
    'Dimanche',
    'Lundi',
    'Mardi',
    'Mercredi',
    'Jeudi',
    'Vendredi',
    'Samedi'
  ],
  dayNamesShort: ['Dim.', 'Lun.', 'Mar.', 'Mer.', 'Jeu.', 'Ven.', 'Sam.'],
  today: "Aujourd'hui"
};

// Set as default locale
LocaleConfig.defaultLocale = 'fr';

​
Configuration

​
Setting up a locale

Define locale configurations by adding them to LocaleConfig.locales: 
LocaleConfig.locales['locale-key'] = {
  monthNames: [],
  monthNamesShort: [],
  dayNames: [],
  dayNamesShort: [],
  today: '',
  formatAccessibilityLabel: '',
  numbers: []
};

​
Locale properties

​
monthNames
string[]
required
Array of full month names, starting with January (12 items).
monthNames: [
  'January', 'February', 'March', 'April',
  'May', 'June', 'July', 'August',
  'September', 'October', 'November', 'December'
]
​
monthNamesShort
string[]
required
Array of abbreviated month names, starting with January (12 items).
monthNamesShort: [
  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
​
dayNames
string[]
required
Array of full day names, starting with Sunday (7 items).
dayNames: [
  'Sunday', 'Monday', 'Tuesday', 'Wednesday',
  'Thursday', 'Friday', 'Saturday'
]
​
dayNamesShort
string[]
required
Array of abbreviated day names, starting with Sunday (7 items).
dayNamesShort: ['S', 'M', 'T', 'W', 'T', 'F', 'S']
​
today
string
Localized text for “Today” button and label.
today: 'Today'
​
formatAccessibilityLabel
string
Date format string for accessibility labels. Uses XDate format tokens.
formatAccessibilityLabel: "dddd d 'of' MMMM 'of' yyyy"
Common tokens:
  • dddd - Full day name
  • d - Day of month
  • MMMM - Full month name
  • yyyy - Full year
​
numbers
string[]
Array of localized number characters (0-9) for number formatting.
// Arabic-Indic numerals
numbers: ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩']

​
Setting default locale

LocaleConfig.defaultLocale = 'locale-key';

​
Complete examples

​
English locale

import { LocaleConfig } from 'react-native-calendars';

LocaleConfig.locales['en'] = {
  formatAccessibilityLabel: "dddd d 'of' MMMM 'of' yyyy",
  monthNames: [
    'January',
    'February',
    'March',
    'April',
    'May',
    'June',
    'July',
    'August',
    'September',
    'October',
    'November',
    'December'
  ],
  monthNamesShort: [
    'Jan',
    'Feb',
    'Mar',
    'Apr',
    'May',
    'Jun',
    'Jul',
    'Aug',
    'Sep',
    'Oct',
    'Nov',
    'Dec'
  ],
  dayNames: [
    'Sunday',
    'Monday',
    'Tuesday',
    'Wednesday',
    'Thursday',
    'Friday',
    'Saturday'
  ],
  dayNamesShort: ['S', 'M', 'T', 'W', 'T', 'F', 'S'],
  today: 'Today'
};

LocaleConfig.defaultLocale = 'en';

​
Spanish locale

import { LocaleConfig } from 'react-native-calendars';

LocaleConfig.locales['es'] = {
  monthNames: [
    'Enero',
    'Febrero',
    'Marzo',
    'Abril',
    'Mayo',
    'Junio',
    'Julio',
    'Agosto',
    'Septiembre',
    'Octubre',
    'Noviembre',
    'Diciembre'
  ],
  monthNamesShort: [
    'Ene',
    'Feb',
    'Mar',
    'Abr',
    'May',
    'Jun',
    'Jul',
    'Ago',
    'Sep',
    'Oct',
    'Nov',
    'Dic'
  ],
  dayNames: [
    'Domingo',
    'Lunes',
    'Martes',
    'Miércoles',
    'Jueves',
    'Viernes',
    'Sábado'
  ],
  dayNamesShort: ['D', 'L', 'M', 'X', 'J', 'V', 'S'],
  today: 'Hoy'
};

LocaleConfig.defaultLocale = 'es';

​
Hebrew locale with RTL support

import { LocaleConfig } from 'react-native-calendars';

LocaleConfig.locales['he'] = {
  formatAccessibilityLabel: "dddd d 'של' MMMM 'של' yyyy",
  monthNames: [
    'ינואר',
    'פברואר',
    'מרץ',
    'אפריל',
    'מאי',
    'יוני',
    'יולי',
    'אוגוסט',
    'ספטמבר',
    'אוקטובר',
    'נובמבר',
    'דצמבר'
  ],
  monthNamesShort: [
    'ינו',
    'פבר',
    'מרץ',
    'אפר',
    'מאי',
    'יונ',
    'יול',
    'אוג',
    'ספט',
    'אוק',
    'נוב',
    'דצמ'
  ],
  dayNames: [
    'ראשון',
    'שני',
    'שלישי',
    'רביעי',
    'חמישי',
    'שישי',
    'שבת'
  ],
  dayNamesShort: ['א', 'ב', 'ג', 'ד', 'ה', 'ו', 'ש'],
  today: 'היום'
};

LocaleConfig.defaultLocale = 'he';

​
Arabic locale with number localization

import { LocaleConfig } from 'react-native-calendars';

LocaleConfig.locales['ar'] = {
  monthNames: [
    'يناير',
    'فبراير',
    'مارس',
    'أبريل',
    'مايو',
    'يونيو',
    'يوليو',
    'أغسطس',
    'سبتمبر',
    'أكتوبر',
    'نوفمبر',
    'ديسمبر'
  ],
  monthNamesShort: [
    'ينا',
    'فبر',
    'مار',
    'أبر',
    'ماي',
    'يون',
    'يول',
    'أغس',
    'سبت',
    'أكت',
    'نوف',
    'ديس'
  ],
  dayNames: [
    'الأحد',
    'الإثنين',
    'الثلاثاء',
    'الأربعاء',
    'الخميس',
    'الجمعة',
    'السبت'
  ],
  dayNamesShort: ['أحد', 'إثن', 'ثلا', 'أرب', 'خمي', 'جمع', 'سبت'],
  today: 'اليوم',
  numbers: ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩']
};

LocaleConfig.defaultLocale = 'ar';

​
Dynamic locale switching

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { Calendar, LocaleConfig } from 'react-native-calendars';

// Configure locales
LocaleConfig.locales['en'] = {
  monthNames: ['January', 'February', /* ... */],
  monthNamesShort: ['Jan', 'Feb', /* ... */],
  dayNames: ['Sunday', 'Monday', /* ... */],
  dayNamesShort: ['S', 'M', /* ... */],
  today: 'Today'
};

LocaleConfig.locales['es'] = {
  monthNames: ['Enero', 'Febrero', /* ... */],
  monthNamesShort: ['Ene', 'Feb', /* ... */],
  dayNames: ['Domingo', 'Lunes', /* ... */],
  dayNamesShort: ['D', 'L', /* ... */],
  today: 'Hoy'
};

const App = () => {
  const [locale, setLocale] = useState('en');
  const [key, setKey] = useState(0);

  const changeLocale = (newLocale) => {
    LocaleConfig.defaultLocale = newLocale;
    setLocale(newLocale);
    // Force calendar re-render
    setKey(prev => prev + 1);
  };

  return (
    <View>
      <View style={{ flexDirection: 'row', marginBottom: 10 }}>
        <Button title="English" onPress={() => changeLocale('en')} />
        <Button title="Español" onPress={() => changeLocale('es')} />
      </View>
      <Calendar key={key} />
    </View>
  );
};

​
Important notes

LocaleConfig changes are global and affect all calendar components. Configure locales before rendering any calendars, typically in your app’s entry point.
When changing locale dynamically, you may need to force calendar components to re-render using a key prop or state update.
Day names arrays must start with Sunday (index 0), even if your calendar displays Monday as the first day of the week. Use the firstDay prop on calendar components to change the displayed first day.
  • Calendar - Basic calendar component
  • CalendarUtils - Utility functions including getDefaultLocale()
  • Theme - Styling calendar components

Build docs developers (and LLMs) love

Get started for freeTalk to us