Date & time
Date picker
A segmented field with a calendar attached. Every segment is a labelled spinbutton, so the whole value is editable from the keyboard — and there is no ambiguous “2/3/4” to parse, because the order comes from the locale.
Examples
Single date
`onValueChange` reports a CalendarDate or null. The footer actions are per instance: a filter bar wants Today, a record form usually does not.
9182026
Required, and typeable in the segments or pickable from the calendar.
8142026
Bound to the quarter; anything after 30 September is unreachable.
canonical value: 2026-09-18 · displayed as Sep 18, 2026
<DatePicker value={date} onValueChange={setDate} todayValue={DEMO_TODAY} locale="en-US" />
<DatePicker
locale="en-US"
minValue={new CalendarDate(2026, 7, 1)}
maxValue={new CalendarDate(2026, 9, 30)}
value={quarterEnd}
onValueChange={setQuarterEnd}
/>Dates you cannot book
`isDateUnavailable` keeps a day in the grid — focusable and announced — but refuses to select it. A quiet, honest refusal beats a date that silently disappears.
9182026
Weekends and 21–24 September are unavailable.
<DatePicker
locale="en-US"
todayValue={DEMO_TODAY}
defaultValue={new CalendarDate(2026, 9, 18)}
isDateUnavailable={(value) => isWeekend(value, "en-US") || (value.day >= 21 && value.day <= 24)}
/>Local date and time
`DateTimePicker` edits a CalendarDateTime: a wall clock with no zone. Two people in different zones see the same 09:30, which is what a market session or a meeting time actually means.
91820260930
Local wall clock, no zone attached.
9182026093015
The field gains a seconds segment, so the value is exact to the second.
canonical value: Sep 18, 2026, 09:30 AM
<DateTimePicker
locale="en-US"
hourCycle={24}
value={local}
onValueChange={setLocal}
todayValue={DEMO_TODAY}
/>Zoned date and time
A ZonedDateTime carries its own identifier. The component never converts it, never guesses a zone and never drops the offset — “09:30 Berlin” stays 09:30 Berlin.
91820260930GMT+2
Europe/Berlin; DST is the zone's business, not the field's.
91820260930GMT+9
A different zone is a different value, on purpose.
serialised: 2026-09-18T09:30:00+02:00[Europe/Berlin] · absolute: 2026-09-18T07:30:00.000Z
<ZonedDateTimePicker
locale="en-US"
hourCycle={24}
value={zoned}
onValueChange={setZoned}
todayValue={DEMO_TODAY}
/>A field with no calendar
`DateField` is the same segmented control without the popover — for a dense filter bar where a month grid would be too much surface.
01092026
26092026
9262026
The same value, US ordering.
<FieldGroup columns={3}>
<Field label="From">
<DateField locale="en-GB" defaultValue={new CalendarDate(2026, 9, 1)} />
</Field>
<Field label="To">
<DateField locale="en-GB" defaultValue={new CalendarDate(2026, 9, 26)} />
</Field>
<Field label="Locale order" description="The same value, US ordering.">
<DateField locale="en-US" defaultValue={new CalendarDate(2026, 9, 26)} />
</Field>
</FieldGroup>States
One shell, five states plus the size scale — the same shell every other control in the library uses, so a date field never looks like a different product.
mmddyyyy
Empty
9182026
Filled
9182026
That date is a holiday
Invalid
mmddyyyy
Disabled
9182026
Read-only
9182026
Small
<DatePicker aria-label="Empty date" locale="en-US" />
<DatePicker aria-label="Filled date" locale="en-US" defaultValue={new CalendarDate(2026, 9, 18)} />
<Field label="Settlement" error="That date is a holiday">
<DatePicker locale="en-US" defaultValue={new CalendarDate(2026, 9, 18)} />
</Field>
<DatePicker aria-label="Disabled" locale="en-US" disabled />
<DatePicker aria-label="Read-only" locale="en-US" readOnly defaultValue={new CalendarDate(2026, 9, 18)} />
<DatePicker aria-label="Small date" locale="en-US" size="sm" defaultValue={new CalendarDate(2026, 9, 18)} />Usage
import { DateField, DatePicker, DateTimePicker } from "@luc/ui";<DatePicker aria-label="Settlement" value={date} onValueChange={setDate} />Choose the component by the value it stores, not by how it looks: `DateField` and `DatePicker` edit a `CalendarDate`, `DateTimePicker` a `CalendarDateTime`, `ZonedDateTimePicker` a `ZonedDateTime`. Nothing is converted for you, because converting an instant into a date is a decision the product has to make.
API
Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.
| Export | Kind | Signature |
|---|---|---|
DateField | 60 documented props | <T extends DateValue = DateValue>({ size, invalid, disabled, readOnly, className, trailingAction, ...props }: DateFieldProps<T>) => import("@types/react").JSX.Element |
DatePicker | 60 documented props | <T extends DateValue = DateValue>({ onValueChange, size, invalid, disabled, readOnly, required, locale, viewSwitch, showTodayAction, showClearAction, calendarButtonLabel, footer, className, todayValu… |
DateRangePicker | 60 documented props | <T extends DateValue = DateValue>({ onValueChange, size, invalid, disabled, readOnly, required, locale, months, presets, showTodayAction, showClearAction, calendarButtonLabel, footer, className, toda… |
| Export | Kind | Signature |
|---|---|---|
DateTimePicker | 60 documented props | ({ granularity, ...props }: DateTimePickerProps) => import("@types/react").JSX.Element |
ZonedDateTimePicker | 60 documented props | ({ granularity, ...props }: ZonedDateTimePickerProps) => import("@types/react").JSX.Element |
DatePicker props
Type: DatePickerProps<T>
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
aria-describedby?inherited | string | undefined | — | Identifies the element (or elements) that describes the object. |
aria-details?inherited | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. |
aria-label?inherited | string | undefined | — | Defines a string value that labels the current element. |
aria-labelledby?inherited | string | undefined | — | Identifies the element (or elements) that labels the current element. |
autoComplete?inherited | string | undefined | — | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete… |
autoFocus?inherited | boolean | undefined | — | Whether the element should receive focus on render. |
calendarButtonLabel? | string | undefined | — | Accessible name for the calendar button. Localized by React Aria by default. |
className? | string | undefined | — | |
defaultOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (uncontrolled). |
defaultValue?inherited | T | null | undefined | — | The default value (uncontrolled). |
dir?inherited | string | undefined | — | |
disabled? | boolean | undefined | — | |
firstDayOfWeek?inherited | "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | undefined | — | The day that starts the week. |
footer? | ReactNode | — | Extra footer content beside the quick actions. |
form?inherited | string | undefined | — | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs… |
granularity?inherited | Granularity | undefined | — | Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times. |
hidden?inherited | boolean | undefined | — | |
hideTimeZone?inherited | boolean | undefined | | Whether to hide the time zone abbreviation. |
hourCycle?inherited | 24 | 12 | undefined | — | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
id?inherited | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
inert?inherited | boolean | undefined | — | |
invalid? | boolean | undefined | — | |
isDateUnavailable?inherited | ((date: DateValue) => boolean) | undefined | — | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. |
isOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (controlled). |
lang?inherited | string | undefined | — | |
locale? | string | undefined | — | |
maxValue?inherited | DateValue | null | undefined | — | The maximum allowed date that a user may select. |
minValue?inherited | DateValue | null | undefined | — | The minimum allowed date that a user may select. |
name?inherited | string | undefined | — | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
onAnimationEnd?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationEndCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIteration?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIterationCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStart?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStartCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAuxClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onAuxClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onBlur?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. |
onClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenu?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenuCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onFocus?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. |
onFocusChange?inherited | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. |
onGotPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onGotPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onKeyDown?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. |
onKeyUp?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. |
onLostPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onLostPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onMouseDown?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseDownCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseEnter?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseLeave?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMove?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMoveCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOut?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOutCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — |
DateTimePicker props
Type: DateTimePickerProps
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
aria-describedby?inherited | string | undefined | — | Identifies the element (or elements) that describes the object. |
aria-details?inherited | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. |
aria-label?inherited | string | undefined | — | Defines a string value that labels the current element. |
aria-labelledby?inherited | string | undefined | — | Identifies the element (or elements) that labels the current element. |
autoComplete?inherited | string | undefined | — | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete… |
autoFocus?inherited | boolean | undefined | — | Whether the element should receive focus on render. |
calendarButtonLabel? | string | undefined | — | Accessible name for the calendar button. Localized by React Aria by default. |
className? | string | undefined | — | |
defaultOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (uncontrolled). |
defaultValue?inherited | CalendarDateTime | null | undefined | — | The default value (uncontrolled). |
dir?inherited | string | undefined | — | |
disabled? | boolean | undefined | — | |
firstDayOfWeek?inherited | "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | undefined | — | The day that starts the week. |
footer? | ReactNode | — | Extra footer content beside the quick actions. |
form?inherited | string | undefined | — | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs… |
granularity? | "minute" | "second" | undefined | — | `minute` (default) or `second`. |
hidden?inherited | boolean | undefined | — | |
hideTimeZone?inherited | boolean | undefined | | Whether to hide the time zone abbreviation. |
hourCycle?inherited | 24 | 12 | undefined | — | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
id?inherited | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
inert?inherited | boolean | undefined | — | |
invalid? | boolean | undefined | — | |
isDateUnavailable?inherited | ((date: DateValue) => boolean) | undefined | — | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. |
isOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (controlled). |
lang?inherited | string | undefined | — | |
locale? | string | undefined | — | |
maxValue?inherited | DateValue | null | undefined | — | The maximum allowed date that a user may select. |
minValue?inherited | DateValue | null | undefined | — | The minimum allowed date that a user may select. |
name?inherited | string | undefined | — | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
onAnimationEnd?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationEndCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIteration?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIterationCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStart?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStartCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAuxClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onAuxClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onBlur?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. |
onClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenu?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenuCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onFocus?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. |
onFocusChange?inherited | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. |
onGotPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onGotPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onKeyDown?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. |
onKeyUp?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. |
onLostPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onLostPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onMouseDown?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseDownCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseEnter?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseLeave?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMove?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMoveCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOut?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOutCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — |
DateField props60 props
DateField props
Type: DateFieldProps<T>
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
aria-describedby?inherited | string | undefined | — | Identifies the element (or elements) that describes the object. |
aria-details?inherited | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. |
aria-label?inherited | string | undefined | — | Defines a string value that labels the current element. |
aria-labelledby?inherited | string | undefined | — | Identifies the element (or elements) that labels the current element. |
autoComplete?inherited | string | undefined | — | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete… |
autoFocus?inherited | boolean | undefined | — | Whether the element should receive focus on render. |
className? | string | undefined | — | |
defaultValue?inherited | T | null | undefined | — | The default value (uncontrolled). |
dir?inherited | string | undefined | — | |
disabled? | boolean | undefined | — | |
form?inherited | string | undefined | — | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs… |
granularity?inherited | Granularity | undefined | — | Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times. |
hidden?inherited | boolean | undefined | — | |
hideTimeZone?inherited | boolean | undefined | | Whether to hide the time zone abbreviation. |
hourCycle?inherited | 24 | 12 | undefined | — | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
id?inherited | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
inert?inherited | boolean | undefined | — | |
invalid? | boolean | undefined | — | |
isDateUnavailable?inherited | ((date: DateValue) => boolean) | undefined | — | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. |
isRequired?inherited | boolean | undefined | — | Whether user input is required on the input before form submission. |
lang?inherited | string | undefined | — | |
locale? | string | undefined | — | BCP-47 locale for segment order, weekday names and the visible month. |
maxValue?inherited | DateValue | null | undefined | — | The maximum allowed date that a user may select. |
minValue?inherited | DateValue | null | undefined | — | The minimum allowed date that a user may select. |
name?inherited | string | undefined | — | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
onAnimationEnd?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationEndCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIteration?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIterationCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStart?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStartCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAuxClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onAuxClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onBlur?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. |
onChange?inherited | ((value: MappedDateValue<T> | null) => void) | undefined | — | Handler that is called when the value changes. |
onClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenu?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenuCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onFocus?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. |
onFocusChange?inherited | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. |
onGotPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onGotPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onKeyDown?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. |
onKeyUp?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. |
onLostPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onLostPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onMouseDown?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseDownCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseEnter?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseLeave?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMove?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMoveCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOut?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOutCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOver?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOverCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseUp?inherited | MouseEventHandler<HTMLDivElement> | undefined | — |
DateRangePicker props60 props
DateRangePicker props
Type: DateRangePickerProps<T>
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
allowsNonContiguousRanges?inherited | boolean | undefined | — | When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected. |
aria-describedby?inherited | string | undefined | — | Identifies the element (or elements) that describes the object. |
aria-details?inherited | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. |
aria-label?inherited | string | undefined | — | Defines a string value that labels the current element. |
aria-labelledby?inherited | string | undefined | — | Identifies the element (or elements) that labels the current element. |
autoFocus?inherited | boolean | undefined | — | Whether the element should receive focus on render. |
calendarButtonLabel? | string | undefined | — | |
className? | string | undefined | — | |
defaultOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (uncontrolled). |
defaultValue?inherited | RangeValue<T> | null | undefined | — | The default value (uncontrolled). |
dir?inherited | string | undefined | — | |
disabled? | boolean | undefined | — | |
firstDayOfWeek?inherited | "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | undefined | — | The day that starts the week. |
footer? | ReactNode | — | |
form?inherited | string | undefined | — | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs… |
granularity?inherited | Granularity | undefined | — | Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times. |
hidden?inherited | boolean | undefined | — | |
hideTimeZone?inherited | boolean | undefined | | Whether to hide the time zone abbreviation. |
hourCycle?inherited | 24 | 12 | undefined | — | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
id?inherited | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
inert?inherited | boolean | undefined | — | |
invalid? | boolean | undefined | — | |
isDateUnavailable?inherited | ((date: DateValue, anchorDate: CalendarDate | null) => boolean) | undefined | — | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. |
isOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (controlled). |
lang?inherited | string | undefined | — | |
locale? | string | undefined | — | |
maxValue?inherited | DateValue | null | undefined | — | The maximum allowed date that a user may select. |
minValue?inherited | DateValue | null | undefined | — | The minimum allowed date that a user may select. |
months? | 1 | 2 | undefined | — | Months shown at once. Default `2`; the caller drops to 1 on mobile. |
onAnimationEnd?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationEndCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIteration?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIterationCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStart?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStartCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAuxClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onAuxClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onBlur?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. |
onClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenu?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenuCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onFocus?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. |
onFocusChange?inherited | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. |
onGotPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onGotPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onKeyDown?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. |
onKeyUp?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. |
onLostPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onLostPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onMouseDown?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseDownCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseEnter?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseLeave?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMove?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMoveCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOut?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOutCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — |
ZonedDateTimePicker props60 props
ZonedDateTimePicker props
Type: ZonedDateTimePickerProps
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
aria-describedby?inherited | string | undefined | — | Identifies the element (or elements) that describes the object. |
aria-details?inherited | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. |
aria-label?inherited | string | undefined | — | Defines a string value that labels the current element. |
aria-labelledby?inherited | string | undefined | — | Identifies the element (or elements) that labels the current element. |
autoComplete?inherited | string | undefined | — | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete… |
autoFocus?inherited | boolean | undefined | — | Whether the element should receive focus on render. |
calendarButtonLabel? | string | undefined | — | Accessible name for the calendar button. Localized by React Aria by default. |
className? | string | undefined | — | |
defaultOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (uncontrolled). |
defaultValue?inherited | ZonedDateTime | null | undefined | — | The default value (uncontrolled). |
dir?inherited | string | undefined | — | |
disabled? | boolean | undefined | — | |
firstDayOfWeek?inherited | "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | undefined | — | The day that starts the week. |
footer? | ReactNode | — | Extra footer content beside the quick actions. |
form?inherited | string | undefined | — | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs… |
granularity? | "minute" | "second" | undefined | — | |
hidden?inherited | boolean | undefined | — | |
hideTimeZone?inherited | boolean | undefined | | Whether to hide the time zone abbreviation. |
hourCycle?inherited | 24 | 12 | undefined | — | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
id?inherited | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
inert?inherited | boolean | undefined | — | |
invalid? | boolean | undefined | — | |
isDateUnavailable?inherited | ((date: DateValue) => boolean) | undefined | — | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. |
isOpen?inherited | boolean | undefined | — | Whether the overlay is open by default (controlled). |
lang?inherited | string | undefined | — | |
locale? | string | undefined | — | |
maxValue?inherited | DateValue | null | undefined | — | The maximum allowed date that a user may select. |
minValue?inherited | DateValue | null | undefined | — | The minimum allowed date that a user may select. |
name?inherited | string | undefined | — | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
onAnimationEnd?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationEndCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIteration?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationIterationCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStart?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAnimationStartCapture?inherited | AnimationEventHandler<HTMLDivElement> | undefined | — | |
onAuxClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onAuxClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onBlur?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. |
onClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenu?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onContextMenuCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClick?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onDoubleClickCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onFocus?inherited | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. |
onFocusChange?inherited | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. |
onGotPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onGotPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onKeyDown?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. |
onKeyUp?inherited | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. |
onLostPointerCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onLostPointerCaptureCapture?inherited | PointerEventHandler<HTMLDivElement> | undefined | — | |
onMouseDown?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseDownCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseEnter?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseLeave?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMove?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseMoveCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOut?inherited | MouseEventHandler<HTMLDivElement> | undefined | — | |
onMouseOutCapture?inherited | MouseEventHandler<HTMLDivElement> | undefined | — |
Guidelines
Do
- Choose the component by the value it stores, not by the layout: a date is `DatePicker`, a wall clock is `DateTimePicker`, an instant in a named zone is `ZonedDateTimePicker`.
- Separate the two constraints — `minValue`/`maxValue` bound the range a value may fall in, `isDateUnavailable` names the exceptions inside it.
- Pass `todayValue` wherever the result has to be reproducible (a demo, a test, a server render), so the Today action cannot mean a different day tomorrow.
- Use `DateField` in a dense filter bar where a month grid would be too much surface; it is the same segmented control without the popover.
Don't
- Substitute a plain text input for the segmented field: the segments are the keyboard contract, and their order is the locale's rather than the one you guessed.
- Convert a zoned value to a date inside the component's value — `ZonedDateTimePicker` keeps the identifier it was given, and dropping it is a product decision.
- Rely on `required` for the message: it marks the control, `Field` with an `error` explains it.
Accessibility
The field is one tab stop whose segments take arrow keys (Up and Down step a segment, Tab leaves the field), and a partially typed date is announced as incomplete rather than as an error. The calendar button is a second tab stop with its own name, the popover returns focus to the field when it closes, and `isDateUnavailable` reports through `aria-disabled` so a blocked day is announced as unavailable rather than as absent.
Related