DateTimeField
Segmented date, date-range, time, or time-range field selected with a required mode.
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.
Interactive example
Loading interactive example
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 |