0
# Field Components
1

2
Standalone input field components for date, time, and date-time values with sectioned editing, keyboard navigation, and validation support.
3

4
## Capabilities
5

6
### DateField
7

8
Standalone date input field with sectioned editing and keyboard navigation.
9

10
```typescript { .api }
11
/**
12
 * Standalone date input field component
13
 * @param props - DateField configuration properties
14
 * @returns JSX element for date field
15
 */
16
function DateField<TDate>(props: DateFieldProps<TDate>): JSX.Element;
17

18
interface DateFieldProps<TDate> {
19
  /** Current date value */
20
  value?: TDate | null;
21
  /** Default date value for uncontrolled component */
22
  defaultValue?: TDate | null;
23
  /** Callback fired when date changes */
24
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
25
  /** Format string for date display */
26
  format?: string;
27
  /** Input label text */
28
  label?: React.ReactNode;
29
  /** If true, the field is disabled */
30
  disabled?: boolean;
31
  /** If true, the field is read-only */
32
  readOnly?: boolean;
33
  /** If true, the field is required */
34
  required?: boolean;
35
  /** If true, respect leading zeros in format */
36
  shouldRespectLeadingZeros?: boolean;
37
  /** Selected sections */
38
  selectedSections?: FieldSelectedSections;
39
  /** Callback when selected sections change */
40
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
41
  /** Reference to field methods */
42
  ref?: React.Ref<FieldRef<TDate>>;
43
  /** Input placeholder text */
44
  placeholder?: string;
45
  /** Helper text */
46
  helperText?: React.ReactNode;
47
  /** If true, field has error state */
48
  error?: boolean;
49
  /** Additional props for text field */
50
  InputProps?: Partial<InputProps>;
51
  /** Additional CSS classes */
52
  className?: string;
53
  /** Inline styles */
54
  sx?: SxProps<Theme>;
55
}
56

57
interface FieldChangeContext<TDate> {
58
  validationError: string | null;
59
}
60

61
type FieldSelectedSections = number | FieldSectionType | null | 'all';
62
type FieldSectionType = 'year' | 'month' | 'day' | 'weekDay' | 'hours' | 'minutes' | 'seconds' | 'meridiem' | 'empty';
63
```
64

65
### TimeField
66

67
Standalone time input field with sectioned editing for hours, minutes, and seconds.
68

69
```typescript { .api }
70
/**
71
 * Standalone time input field component
72
 * @param props - TimeField configuration properties
73
 * @returns JSX element for time field
74
 */
75
function TimeField<TDate>(props: TimeFieldProps<TDate>): JSX.Element;
76

77
interface TimeFieldProps<TDate> {
78
  /** Current time value */
79
  value?: TDate | null;
80
  /** Default time value for uncontrolled component */
81
  defaultValue?: TDate | null;
82
  /** Callback fired when time changes */
83
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
84
  /** Format string for time display */
85
  format?: string;
86
  /** Input label text */
87
  label?: React.ReactNode;
88
  /** If true, the field is disabled */
89
  disabled?: boolean;
90
  /** If true, the field is read-only */
91
  readOnly?: boolean;
92
  /** If true, the field is required */
93
  required?: boolean;
94
  /** If true, respect leading zeros in format */
95
  shouldRespectLeadingZeros?: boolean;
96
  /** Selected sections */
97
  selectedSections?: FieldSelectedSections;
98
  /** Callback when selected sections change */
99
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
100
  /** If true, use 12-hour format with AM/PM */
101
  ampm?: boolean;
102
  /** Reference to field methods */
103
  ref?: React.Ref<FieldRef<TDate>>;
104
  /** Input placeholder text */
105
  placeholder?: string;
106
  /** Helper text */
107
  helperText?: React.ReactNode;
108
  /** If true, field has error state */
109
  error?: boolean;
110
  /** Additional props for text field */
111
  InputProps?: Partial<InputProps>;
112
  /** Additional CSS classes */
113
  className?: string;
114
  /** Inline styles */
115
  sx?: SxProps<Theme>;
116
}
117
```
118

119
### DateTimeField
120

121
Standalone date-time input field combining date and time sections with full keyboard navigation.
122

123
```typescript { .api }
124
/**
125
 * Standalone date-time input field component
126
 * @param props - DateTimeField configuration properties
127
 * @returns JSX element for date-time field
128
 */
129
function DateTimeField<TDate>(props: DateTimeFieldProps<TDate>): JSX.Element;
130

131
interface DateTimeFieldProps<TDate> {
132
  /** Current date-time value */
133
  value?: TDate | null;
134
  /** Default date-time value for uncontrolled component */
135
  defaultValue?: TDate | null;
136
  /** Callback fired when date-time changes */
137
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
138
  /** Format string for date-time display */
139
  format?: string;
140
  /** Input label text */
141
  label?: React.ReactNode;
142
  /** If true, the field is disabled */
143
  disabled?: boolean;
144
  /** If true, the field is read-only */
145
  readOnly?: boolean;
146
  /** If true, the field is required */
147
  required?: boolean;
148
  /** If true, respect leading zeros in format */
149
  shouldRespectLeadingZeros?: boolean;
150
  /** Selected sections */
151
  selectedSections?: FieldSelectedSections;
152
  /** Callback when selected sections change */
153
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
154
  /** If true, use 12-hour format with AM/PM */
155
  ampm?: boolean;
156
  /** Reference to field methods */
157
  ref?: React.Ref<FieldRef<TDate>>;
158
  /** Input placeholder text */
159
  placeholder?: string;
160
  /** Helper text */
161
  helperText?: React.ReactNode;
162
  /** If true, field has error state */
163
  error?: boolean;
164
  /** Additional props for text field */
165
  InputProps?: Partial<InputProps>;
166
  /** Additional CSS classes */
167
  className?: string;
168
  /** Inline styles */
169
  sx?: SxProps<Theme>;
170
}
171
```
172

173
**Usage Examples:**
174

175
```typescript
176
import { DateField, TimeField, DateTimeField } from '@mui/x-date-pickers';
177
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
178
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
179
import dayjs, { Dayjs } from 'dayjs';
180

181
// Basic field usage
182
function BasicFields() {
183
  const [dateValue, setDateValue] = React.useState<Dayjs | null>(null);
184
  const [timeValue, setTimeValue] = React.useState<Dayjs | null>(null);
185
  const [dateTimeValue, setDateTimeValue] = React.useState<Dayjs | null>(null);
186
  
187
  return (
188
    <LocalizationProvider dateAdapter={AdapterDayjs}>
189
      <DateField
190
        label="Date"
191
        value={dateValue}
192
        onChange={(newValue) => setDateValue(newValue)}
193
        format="MM/DD/YYYY"
194
      />
195
      <TimeField
196
        label="Time"
197
        value={timeValue}
198
        onChange={(newValue) => setTimeValue(newValue)}
199
        format="HH:mm:ss"
200
        ampm={false}
201
      />
202
      <DateTimeField
203
        label="Date & Time"
204
        value={dateTimeValue}
205
        onChange={(newValue) => setDateTimeValue(newValue)}
206
        format="MM/DD/YYYY HH:mm"
207
      />
208
    </LocalizationProvider>
209
  );
210
}
211

212
// Field with validation
213
function ValidatedField() {
214
  const [value, setValue] = React.useState<Dayjs | null>(null);
215
  const [error, setError] = React.useState<string | null>(null);
216
  
217
  const handleChange = (newValue: Dayjs | null, context: FieldChangeContext<Dayjs>) => {
218
    setValue(newValue);
219
    setError(context.validationError);
220
  };
221
  
222
  return (
223
    <LocalizationProvider dateAdapter={AdapterDayjs}>
224
      <DateField
225
        label="Required Date"
226
        value={value}
227
        onChange={handleChange}
228
        required
229
        error={!!error}
230
        helperText={error || 'Please enter a date'}
231
      />
232
    </LocalizationProvider>
233
  );
234
}
235
```
236

237
## Unstable Field Hooks
238

239
### unstable_useDateField
240

241
Hook providing the logic for date field components.
242

243
```typescript { .api }
244
/**
245
 * Hook for date field functionality
246
 * @param props - UseDateField configuration properties
247
 * @returns Field state and handlers
248
 */
249
function unstable_useDateField<TDate>(props: UseDateFieldProps<TDate>): UseFieldReturnValue<TDate>;
250

251
interface UseDateFieldProps<TDate> {
252
  value?: TDate | null;
253
  defaultValue?: TDate | null;
254
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
255
  format?: string;
256
  disabled?: boolean;
257
  readOnly?: boolean;
258
  shouldRespectLeadingZeros?: boolean;
259
  selectedSections?: FieldSelectedSections;
260
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
261
}
262
```
263

264
### unstable_useTimeField
265

266
Hook providing the logic for time field components.
267

268
```typescript { .api }
269
/**
270
 * Hook for time field functionality
271
 * @param props - UseTimeField configuration properties
272
 * @returns Field state and handlers
273
 */
274
function unstable_useTimeField<TDate>(props: UseTimeFieldProps<TDate>): UseFieldReturnValue<TDate>;
275

276
interface UseTimeFieldProps<TDate> {
277
  value?: TDate | null;
278
  defaultValue?: TDate | null;
279
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
280
  format?: string;
281
  disabled?: boolean;
282
  readOnly?: boolean;
283
  shouldRespectLeadingZeros?: boolean;
284
  selectedSections?: FieldSelectedSections;
285
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
286
  ampm?: boolean;
287
}
288
```
289

290
### unstable_useDateTimeField
291

292
Hook providing the logic for date-time field components.
293

294
```typescript { .api }
295
/**
296
 * Hook for date-time field functionality
297
 * @param props - UseDateTimeField configuration properties
298
 * @returns Field state and handlers
299
 */
300
function unstable_useDateTimeField<TDate>(props: UseDateTimeFieldProps<TDate>): UseFieldReturnValue<TDate>;
301

302
interface UseDateTimeFieldProps<TDate> {
303
  value?: TDate | null;
304
  defaultValue?: TDate | null;
305
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
306
  format?: string;
307
  disabled?: boolean;
308
  readOnly?: boolean;
309
  shouldRespectLeadingZeros?: boolean;
310
  selectedSections?: FieldSelectedSections;
311
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
312
  ampm?: boolean;
313
}
314
```
315

316
## Field Types
317

318
### FieldRef Interface
319

320
Reference interface for field components providing programmatic control.
321

322
```typescript { .api }
323
interface FieldRef<TDate> {
324
  /**
325
   * Returns the sections of the current value
326
   * @returns Array of field sections
327
   */
328
  getSections(): FieldSection[];
329
  /**
330
   * Returns the index of the active section (the first focused section)
331
   * @returns Index of active section or null if none active
332
   */
333
  getActiveSectionIndex(): number | null;
334
  /**
335
   * Updates the selected sections
336
   * @param selectedSections - Sections to select
337
   */
338
  setSelectedSections(selectedSections: FieldSelectedSections): void;
339
  /**
340
   * Focuses the field
341
   * @param newSelectedSection - Section to select once focused
342
   */
343
  focusField(newSelectedSection?: number | FieldSectionType): void;
344
  /**
345
   * Returns true if the field is focused
346
   * @returns Boolean indicating focus state
347
   */
348
  isFieldFocused(): boolean;
349
}
350
```
351

352
### FieldSection Interface
353

354
Represents a single editable section within a field.
355

356
```typescript { .api }
357
interface FieldSection {
358
  /** Value of the section as rendered in input */
359
  value: string;
360
  /** Format token used to parse this section */
361
  format: string;
362
  /** Maximum length of the value for digit sections */
363
  maxLength: number | null;
364
  /** Placeholder when section value is empty */
365
  placeholder: string;
366
  /** Type of the section */
367
  type: FieldSectionType;
368
  /** Content type determining editing behavior */
369
  contentType: FieldSectionContentType;
370
  /** If true, format expects leading zeros */
371
  hasLeadingZerosInFormat: boolean;
372
  /** If true, input should show leading zeros */
373
  hasLeadingZerosInInput: boolean;
374
  /** If true, section has been modified */
375
  modified: boolean;
376
  /** Separator displayed before section value */
377
  startSeparator: string;
378
  /** Separator displayed after section value */
379
  endSeparator: string;
380
  /** If true, end separator is a format separator */
381
  isEndFormatSeparator?: boolean;
382
}
383

384
type FieldSectionContentType = 'digit' | 'digit-with-letter' | 'letter';
385
```
386

387
### UseFieldReturnValue Interface
388

389
Return value from field hooks containing field state and handlers.
390

391
```typescript { .api }
392
interface UseFieldReturnValue<TDate> {
393
  /** Input value for controlled text field */
394
  value: string;
395
  /** Input change handler */
396
  onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
397
  /** Input focus handler */
398
  onFocus: (event: React.FocusEvent<HTMLInputElement>) => void;
399
  /** Input blur handler */
400
  onBlur: (event: React.FocusEvent<HTMLInputElement>) => void;
401
  /** Key down event handler */
402
  onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
403
  /** Click event handler */
404
  onClick: (event: React.MouseEvent<HTMLInputElement>) => void;
405
  /** Paste event handler */
406
  onPaste: (event: React.ClipboardEvent<HTMLInputElement>) => void;
407
  /** Input selection start */
408
  selectionStart: number | null;
409
  /** Input selection end */
410
  selectionEnd: number | null;
411
  /** Current field sections */
412
  sections: FieldSection[];
413
  /** Active section index */
414
  activeSectionIndex: number | null;
415
  /** Parsed field value */
416
  parsedValue: TDate | null;
417
  /** Validation error message */
418
  validationError: string | null;
419
}
420
```