0
# Adapters and Localization
1

2
Date library adapters and localization provider for configuring date manipulation and internationalization across all picker components.
3

4
## Capabilities
5

6
### LocalizationProvider
7

8
Provider component that configures the date adapter and localization settings for all picker components in its tree.
9

10
```typescript { .api }
11
/**
12
 * Provider component for date adapter and localization
13
 * @param props - LocalizationProvider configuration properties
14
 * @returns JSX element wrapping picker components
15
 */
16
function LocalizationProvider<TDate>(props: LocalizationProviderProps<TDate>): JSX.Element;
17

18
interface LocalizationProviderProps<TDate> {
19
  /** Date adapter instance for date manipulation */
20
  dateAdapter: new (...args: any) => MuiPickersAdapter<TDate>;
21
  /** Locale to use with the date adapter */
22
  adapterLocale?: any;
23
  /** Child components that will have access to the adapter */
24
  children: React.ReactNode;
25
  /** Custom locale text overrides */
26
  localeText?: Partial<PickersLocaleText<TDate>>;
27
}
28

29
/**
30
 * Context for accessing the current date adapter
31
 */
32
const MuiPickersAdapterContext: React.Context<MuiPickersAdapter<any> | null>;
33
```
34

35
### MuiPickersAdapter Interface
36

37
Base adapter interface that all date library adapters must implement.
38

39
```typescript { .api }
40
interface MuiPickersAdapter<TDate> {
41
  /** Date library being wrapped */
42
  lib: string;
43
  /** Current locale */
44
  locale?: any;
45
  /** Formats supported by the adapter */
46
  formats: AdapterFormats;
47
  /** Default timezone */
48
  timezone: string;
49
  
50
  // Date creation and parsing
51
  date(value?: any): TDate | null;
52
  dateWithTimezone(value: any, timezone: string): TDate | null;
53
  parse(value: string, format: string): TDate | null;
54
  
55
  // Date information
56
  isNull(date: TDate | null): boolean;
57
  isValid(value: any): boolean;
58
  format(date: TDate, formatKey: keyof AdapterFormats): string;
59
  formatByString(date: TDate, formatString: string): string;
60
  formatNumber(numberToFormat: string): string;
61
  
62
  // Date manipulation
63
  addYears(date: TDate, amount: number): TDate;
64
  addMonths(date: TDate, amount: number): TDate;
65
  addWeeks(date: TDate, amount: number): TDate;
66
  addDays(date: TDate, amount: number): TDate;
67
  addHours(date: TDate, amount: number): TDate;
68
  addMinutes(date: TDate, amount: number): TDate;
69
  addSeconds(date: TDate, amount: number): TDate;
70
  
71
  // Date comparison
72
  isAfter(date: TDate, value: TDate): boolean;
73
  isBefore(date: TDate, value: TDate): boolean;
74
  isSameYear(date: TDate, comparing: TDate): boolean;
75
  isSameMonth(date: TDate, comparing: TDate): boolean;
76
  isSameDay(date: TDate, comparing: TDate): boolean;
77
  isSameHour(date: TDate, comparing: TDate): boolean;
78
  
79
  // Date extraction
80
  getYear(date: TDate): number;
81
  getMonth(date: TDate): number;
82
  getDate(date: TDate): number;
83
  getHours(date: TDate): number;
84
  getMinutes(date: TDate): number;
85
  getSeconds(date: TDate): number;
86
  getMilliseconds(date: TDate): number;
87
  
88
  // Date setting
89
  setYear(date: TDate, year: number): TDate;
90
  setMonth(date: TDate, month: number): TDate;
91
  setDate(date: TDate, date: number): TDate;
92
  setHours(date: TDate, hours: number): TDate;
93
  setMinutes(date: TDate, minutes: number): TDate;
94
  setSeconds(date: TDate, seconds: number): TDate;
95
  setMilliseconds(date: TDate, milliseconds: number): TDate;
96
  
97
  // Calendar utilities
98
  getDaysInMonth(date: TDate): number;
99
  getWeekdays(): string[];
100
  getWeekArray(date: TDate): TDate[][];
101
  getWeekNumber?(date: TDate): number;
102
  getYearRange(start: TDate, end: TDate): TDate[];
103
}
104

105
interface AdapterFormats {
106
  dayOfMonth: string;
107
  fullDate: string;
108
  fullDateTime: string;
109
  fullDateTime12h: string;
110
  fullDateTime24h: string;
111
  fullDateWithWeekday: string;
112
  fullTime: string;
113
  fullTime12h: string;
114
  fullTime24h: string;
115
  hours12h: string;
116
  hours24h: string;
117
  keyboardDate: string;
118
  keyboardDateTime: string;
119
  keyboardDateTime12h: string;
120
  keyboardDateTime24h: string;
121
  minutes: string;
122
  month: string;
123
  monthAndDate: string;
124
  monthAndYear: string;
125
  monthShort: string;
126
  normalDate: string;
127
  normalDateWithWeekday: string;
128
  seconds: string;
129
  shortDate: string;
130
  year: string;
131
}
132
```
133

134
## Date Library Adapters
135

136
### AdapterDateFns
137

138
Adapter for date-fns library v2 and v3.
139

140
```typescript { .api }
141
/**
142
 * Date adapter for date-fns library
143
 */
144
class AdapterDateFns implements MuiPickersAdapter<Date> {
145
  constructor(options?: { locale?: Locale; formats?: Partial<AdapterFormats> });
146
}
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
153
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
154
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
155
import { enUS, fr } from 'date-fns/locale';
156

157
// Basic usage with English locale
158
function App() {
159
  return (
160
    <LocalizationProvider dateAdapter={AdapterDateFns}>
161
      <DatePicker label="Select date" />
162
    </LocalizationProvider>
163
  );
164
}
165

166
// Usage with French locale
167
function FrenchApp() {
168
  return (
169
    <LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={fr}>
170
      <DatePicker label="Sélectionner une date" />
171
    </LocalizationProvider>
172
  );
173
}
174
```
175

176
### AdapterDayjs
177

178
Adapter for Day.js library with plugin support.
179

180
```typescript { .api }
181
/**
182
 * Date adapter for Day.js library
183
 */
184
class AdapterDayjs implements MuiPickersAdapter<dayjs.Dayjs> {
185
  constructor(options?: { locale?: string; instance?: typeof dayjs; formats?: Partial<AdapterFormats> });
186
}
187
```
188

189
**Usage Examples:**
190

191
```typescript
192
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
193
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
194
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
195
import dayjs from 'dayjs';
196
import 'dayjs/locale/fr';
197
import utc from 'dayjs/plugin/utc';
198
import timezone from 'dayjs/plugin/timezone';
199

200
// Configure dayjs plugins
201
dayjs.extend(utc);
202
dayjs.extend(timezone);
203

204
// Basic usage
205
function App() {
206
  return (
207
    <LocalizationProvider dateAdapter={AdapterDayjs}>
208
      <DatePicker label="Select date" />
209
    </LocalizationProvider>
210
  );
211
}
212

213
// Usage with French locale
214
function FrenchApp() {
215
  return (
216
    <LocalizationProvider dateAdapter={AdapterDayjs} adapterLocale="fr">
217
      <DatePicker label="Sélectionner une date" />
218
    </LocalizationProvider>
219
  );
220
}
221
```
222

223
### AdapterLuxon
224

225
Adapter for Luxon library with timezone support.
226

227
```typescript { .api }
228
/**
229
 * Date adapter for Luxon library
230
 */
231
class AdapterLuxon implements MuiPickersAdapter<luxon.DateTime> {
232
  constructor(options?: { locale?: string; formats?: Partial<AdapterFormats> });
233
}
234
```
235

236
**Usage Examples:**
237

238
```typescript
239
import { AdapterLuxon } from '@mui/x-date-pickers/AdapterLuxon';
240
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
241
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
242

243
// Basic usage
244
function App() {
245
  return (
246
    <LocalizationProvider dateAdapter={AdapterLuxon}>
247
      <DatePicker label="Select date" />
248
    </LocalizationProvider>
249
  );
250
}
251

252
// Usage with French locale
253
function FrenchApp() {
254
  return (
255
    <LocalizationProvider dateAdapter={AdapterLuxon} adapterLocale="fr">
256
      <DatePicker label="Sélectionner une date" />
257
    </LocalizationProvider>
258
  );
259
}
260
```
261

262
### AdapterMoment
263

264
Adapter for Moment.js library.
265

266
```typescript { .api }
267
/**
268
 * Date adapter for Moment.js library
269
 */
270
class AdapterMoment implements MuiPickersAdapter<moment.Moment> {
271
  constructor(options?: { locale?: string; instance?: typeof moment; formats?: Partial<AdapterFormats> });
272
}
273
```
274

275
**Usage Examples:**
276

277
```typescript
278
import { AdapterMoment } from '@mui/x-date-pickers/AdapterMoment';
279
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
280
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
281
import moment from 'moment';
282
import 'moment/locale/fr';
283

284
// Basic usage
285
function App() {
286
  return (
287
    <LocalizationProvider dateAdapter={AdapterMoment}>
288
      <DatePicker label="Select date" />
289
    </LocalizationProvider>
290
  );
291
}
292

293
// Usage with French locale
294
function FrenchApp() {
295
  return (
296
    <LocalizationProvider dateAdapter={AdapterMoment} adapterLocale="fr">
297
      <DatePicker label="Sélectionner une date" />
298
    </LocalizationProvider>
299
  );
300
}
301
```
302

303
## Alternative Calendar Systems
304

305
### AdapterDateFnsJalali
306

307
Adapter for date-fns with Jalali (Persian) calendar support.
308

309
```typescript { .api }
310
/**
311
 * Date adapter for date-fns with Jalali calendar
312
 */
313
class AdapterDateFnsJalali implements MuiPickersAdapter<Date> {
314
  constructor(options?: { locale?: Locale; formats?: Partial<AdapterFormats> });
315
}
316
```
317

318
### AdapterMomentHijri
319

320
Adapter for Moment.js with Hijri (Islamic) calendar support.
321

322
```typescript { .api }
323
/**
324
 * Date adapter for Moment.js with Hijri calendar
325
 */
326
class AdapterMomentHijri implements MuiPickersAdapter<moment.Moment> {
327
  constructor(options?: { locale?: string; formats?: Partial<AdapterFormats> });
328
}
329
```
330

331
### AdapterMomentJalaali
332

333
Adapter for Moment.js with Jalaali (Persian) calendar support.
334

335
```typescript { .api }
336
/**
337
 * Date adapter for Moment.js with Jalaali calendar
338
 */
339
class AdapterMomentJalaali implements MuiPickersAdapter<moment.Moment> {
340
  constructor(options?: { locale?: string; formats?: Partial<AdapterFormats> });
341
}
342
```
343

344
### AdapterDateFnsV2
345

346
Legacy adapter for date-fns v2.x compatibility.
347

348
```typescript { .api }
349
/**
350
 * Date adapter for date-fns v2.x (legacy support)
351
 */
352
class AdapterDateFns implements MuiPickersAdapter<Date> {
353
  constructor(options?: { locale?: Locale; formats?: Partial<AdapterFormats> });
354
}
355
```
356

357
**Usage Examples:**
358

359
```typescript
360
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFnsV2';
361
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
362
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
363
import { enUS } from 'date-fns/locale';
364

365
// Basic usage for date-fns v2.x
366
function App() {
367
  return (
368
    <LocalizationProvider dateAdapter={AdapterDateFns}>
369
      <DatePicker label="Select date" />
370
    </LocalizationProvider>
371
  );
372
}
373

374
// Usage with locale for date-fns v2.x
375
function LocalizedApp() {
376
  return (
377
    <LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={enUS}>
378
      <DatePicker label="Select date" />
379
    </LocalizationProvider>
380
  );
381
}
382
```
383

384
### AdapterDateFnsJalaliV2
385

386
Legacy adapter for date-fns-jalali v2.x with Persian calendar support.
387

388
```typescript { .api }
389
/**
390
 * Date adapter for date-fns-jalali v2.x (legacy Persian calendar support)
391
 */
392
class AdapterDateFnsJalali implements MuiPickersAdapter<Date> {
393
  constructor(options?: { locale?: any; formats?: Partial<AdapterFormats> });
394
}
395
```
396

397
**Usage Examples:**
398

399
```typescript
400
import { AdapterDateFnsJalali } from '@mui/x-date-pickers/AdapterDateFnsJalaliV2';
401
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
402
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
403

404
// Basic usage for date-fns-jalali v2.x
405
function PersianApp() {
406
  return (
407
    <LocalizationProvider dateAdapter={AdapterDateFnsJalali}>
408
      <DatePicker label="انتخاب تاریخ" />
409
    </LocalizationProvider>
410
  );
411
}
412
```
413

414
## Locale Text Configuration
415

416
### PickersLocaleText Interface
417

418
Interface for customizing picker text and translations.
419

420
```typescript { .api }
421
interface PickersLocaleText<TDate> {
422
  // Calendar navigation
423
  previousMonth: string;
424
  nextMonth: string;
425
  
426
  // View switching
427
  openDatePickerDialogue: (value: TDate, utils: MuiPickersAdapter<TDate>) => string;
428
  openTimePickerDialogue: (value: TDate, utils: MuiPickersAdapter<TDate>) => string;
429
  
430
  // Placeholder
431
  fieldYearPlaceholder: (params: { digitAmount: number }) => string;
432
  fieldMonthPlaceholder: (params: { contentType: FieldSectionContentType }) => string;
433
  fieldDayPlaceholder: () => string;
434
  fieldWeekDayPlaceholder: (params: { contentType: FieldSectionContentType }) => string;
435
  fieldHoursPlaceholder: () => string;
436
  fieldMinutesPlaceholder: () => string;
437
  fieldSecondsPlaceholder: () => string;
438
  fieldMeridiemPlaceholder: () => string;
439
  
440
  // Toolbar
441
  datePickerToolbarTitle: string;
442
  timePickerToolbarTitle: string;
443
  dateTimePickerToolbarTitle: string;
444
  
445
  // View names
446
  calendarViewSwitchingButtonAriaLabel: (view: CalendarPickerView) => string;
447
  clockViewSwitchingButtonAriaLabel: (view: ClockPickerView) => string;
448
  
449
  // Actions
450
  cancelButtonLabel: string;
451
  clearButtonLabel: string;
452
  okButtonLabel: string;
453
  todayButtonLabel: string;
454
  
455
  // Start/end labels
456
  start: string;
457
  end: string;
458
}
459

460
type FieldSectionContentType = 'digit' | 'digit-with-letter' | 'letter';
461
type CalendarPickerView = 'year' | 'month' | 'day';
462
type ClockPickerView = 'hours' | 'minutes' | 'seconds';
463
```
464

465
**Usage Examples:**
466

467
```typescript
468
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
469
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
470
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
471

472
// Custom locale text
473
const customLocaleText = {
474
  cancelButtonLabel: 'Annuler',
475
  clearButtonLabel: 'Effacer',
476
  okButtonLabel: 'OK',
477
  todayButtonLabel: 'Aujourd\'hui',
478
  datePickerToolbarTitle: 'Sélectionner la date',
479
  timePickerToolbarTitle: 'Sélectionner l\'heure',
480
  dateTimePickerToolbarTitle: 'Sélectionner la date et l\'heure',
481
  previousMonth: 'Mois précédent',
482
  nextMonth: 'Mois suivant',
483
};
484

485
function CustomizedApp() {
486
  return (
487
    <LocalizationProvider 
488
      dateAdapter={AdapterDayjs} 
489
      localeText={customLocaleText}
490
    >
491
      <DatePicker label="Sélectionner une date" />
492
    </LocalizationProvider>
493
  );
494
}
495
```
496

497
## Timezone Support
498

499
### Timezone Configuration
500

501
```typescript { .api }
502
type PickersTimezone = string | 'default' | 'system';
503

504
interface TimezoneProps {
505
  /** Timezone to use for picker operations */
506
  timezone?: PickersTimezone;
507
}
508
```
509

510
**Usage Examples:**
511

512
```typescript
513
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
514
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
515
import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
516
import dayjs from 'dayjs';
517
import utc from 'dayjs/plugin/utc';
518
import timezone from 'dayjs/plugin/timezone';
519

520
dayjs.extend(utc);
521
dayjs.extend(timezone);
522

523
function TimezoneApp() {
524
  const [value, setValue] = React.useState(dayjs());
525
  
526
  return (
527
    <LocalizationProvider dateAdapter={AdapterDayjs}>
528
      <DateTimePicker
529
        label="New York Time"
530
        value={value}
531
        onChange={(newValue) => setValue(newValue)}
532
        timezone="America/New_York"
533
      />
534
    </LocalizationProvider>
535
  );
536
}
537
```