Date time field
Segmented date, date-range, time, or time-range field selected with a required mode.
Loading interactive example
Choose the required mode for date, date picker, date range, date range picker, time, or time range. Keep storage and time-zone conversion in application code.
DateTimeField
DateTimeField provides segmented date and time entry. Its required mode selects the value shape and available controls.
Purpose
Use DateTimeField when a form needs a structured date, time, or range value. Keep persistent storage and time-zone conversion in application code.
Anatomy
Each mode renders editable keyboard segments. Picker modes add a trigger and keyboard-operable calendar panel. Range modes render separate start and end groups. Provide a visible label or an accessible name for every field.
Modes
| Mode | Use |
|---|---|
date | Enter one date in editable segments. |
date-picker | Enter one date and open a calendar. |
date-range | Enter start and end dates in segments. |
date-range-picker | Select a date range with a calendar and optional presets. |
time | Enter one time in editable segments. |
time-range | Enter start and end times in segments. |
Bind value to the type that the selected mode accepts. Picker modes also accept calendar labels and state.
<DateTimeField
mode="date-range-picker"
bind:value={reportingPeriod}
label="Reporting period"
previousMonthLabel="Previous month"
nextMonthLabel="Next month"
/>Tokens and style hooks
DateTimeField uses input, surface, border, focus, accent, radius, spacing, and floating-layer tokens. Picker panels follow the active Provider boundary.
API
| Member | Type | Kind | Required | Default |
|---|---|---|---|---|
align | 'start' | 'end' | prop | No | 'start' |
disabled | boolean | prop | No | false |
error | string | prop | No | undefined |
formatRange | (range: DateRange) => string | callback | No | formatRangeDefault |
granularity | 'day' | 'hour' | 'minute' | 'second' | prop | No | undefined |
hourCycle | 12 | 24 | prop | No | undefined |
isDateDisabled | (date: DateValue) => boolean | callback | No | undefined |
isDateUnavailable | (date: DateValue) => boolean | callback | No | undefined |
label | string | prop | No | undefined |
locale | string | prop | No | undefined |
maxValue | DateValue | TimeValue | prop | No | undefined |
minValue | DateValue | TimeValue | prop | No | undefined |
mode | 'date' | 'date-picker' | 'date-range' | 'date-range-picker' | 'time' | 'time-range' | prop | Yes | |
nextMonthLabel | string | prop | No | 'Next month' |
numberOfMonths | 1 | 2 | prop | No | date-picker = 1, date-range-picker = 2 |
onValueChange | ((value: DateRange) => void) | ((value: DateValue | undefined) => void) | ((value: TimeRange<T>) => void) | ((value: TimeValue | undefined) => void) | callback | No | undefined |
open | boolean | never | binding | No | false |
openCalendarLabel | string | prop | No | 'Open calendar' |
presets | RangePreset[] | never | prop | No | DEFAULT_PRESETS |
previousMonthLabel | string | prop | No | 'Previous month' |
readonly | boolean | prop | No | false |
size | ControlSize | prop | No | 'md' |
value | DateRange | DateValue | TimeRange<T> | TimeValue | binding | No | date/date-picker/time = undefined, range modes = { start: undefined, end: undefined } |
weekStartsOn | 0 | 1 | prop | No | 1 |