# DateTimeField

DateTimeField provides segmented date and time entry. Its required `mode` selects the value shape and available controls.

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.

<h2 id="purpose">Purpose</h2>

Use DateTimeField when a form needs a structured date, time, or range value. Keep persistent storage and time-zone conversion in application code.

<h2 id="anatomy">Anatomy</h2>

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.

<h2 id="modes">Modes</h2>

| 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.

```svelte
<DateTimeField
	mode="date-range-picker"
	bind:value={reportingPeriod}
	label="Reporting period"
	previousMonthLabel="Previous month"
	nextMonthLabel="Next month"
/>
```

<h2 id="tokens">Tokens and style hooks</h2>

DateTimeField uses input, surface, border, focus, accent, radius, spacing, and floating-layer tokens. Picker panels follow the active Provider boundary.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `align` | `'start' \| 'end'` | prop | No | `'start'` | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `error` | `string` | prop | No | `undefined` | No additional description. |
| `formatRange` | `(range: DateRange) => string` | callback | No | `formatRangeDefault` | No additional description. |
| `granularity` | `'day' \| 'hour' \| 'minute' \| 'second'` | prop | No | `undefined` | No additional description. |
| `hourCycle` | `12 \| 24` | prop | No | `undefined` | No additional description. |
| `isDateDisabled` | `(date: DateValue) => boolean` | callback | No | `undefined` | No additional description. |
| `isDateUnavailable` | `(date: DateValue) => boolean` | callback | No | `undefined` | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `locale` | `string` | prop | No | `undefined` | No additional description. |
| `maxValue` | `DateValue \| TimeValue` | prop | No | `undefined` | No additional description. |
| `minValue` | `DateValue \| TimeValue` | prop | No | `undefined` | No additional description. |
| `mode` | `'date' \| 'date-picker' \| 'date-range' \| 'date-range-picker' \| 'time' \| 'time-range'` | prop | Yes | - | No additional description. |
| `nextMonthLabel` | `string` | prop | No | `'Next month'` | No additional description. |
| `numberOfMonths` | `1 \| 2` | prop | No | `date-picker = 1, date-range-picker = 2` | No additional description. |
| `onValueChange` | `((value: DateRange) => void) \| ((value: DateValue \| undefined) => void) \| ((value: TimeRange<T>) => void) \| ((value: TimeValue \| undefined) => void)` | callback | No | `undefined` | No additional description. |
| `open` | `boolean \| never` | binding | No | `false` | The calendar popover state. Two-way bindable. |
| `openCalendarLabel` | `string` | prop | No | `'Open calendar'` | No additional description. |
| `presets` | `RangePreset[] \| never` | prop | No | `DEFAULT_PRESETS` | No additional description. |
| `previousMonthLabel` | `string` | prop | No | `'Previous month'` | No additional description. |
| `readonly` | `boolean` | prop | No | `false` | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |
| `value` | `DateRange \| DateValue \| TimeRange<T> \| TimeValue` | binding | No | `date/date-picker/time = undefined, range modes = { start: undefined, end: undefined }` | No additional description. |
| `weekStartsOn` | `0 \| 1` | prop | No | `1` | No additional description. |

## Related

- [Calendar](/docs/components/calendar): Single-date calendar grid.