# SvDateTimePicker
A formatted text input plus a portalled dropdown with DATE / TIME tabs - type a
masked value or pick it from a calendar and clock.
Related: [Date & time overview](https://svgrid.com/docs/help/ui-components/date-time/) · [SvCalendar](https://svgrid.com/docs/help/ui-components/sv-calendar/) ·
[SvTimePicker](https://svgrid.com/docs/help/ui-components/sv-time-picker/) · [SvDateRangeInput](https://svgrid.com/docs/help/ui-components/sv-date-range-input/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvDateTimePicker` starter into your app:
Prefer to see it first? `npx @svgrid/ui try date-time-picker` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvDateTimePicker` ships free in
`@svgrid/grid` (no extra date library) and is the **same component SvGrid mounts to
edit a `datetime` cell** - so it is both a standalone control and the grid's
built-in date-time editor:
The examples on this page import from `@svgrid/grid`:
```svelte
```
```ts
import { SvDateTimePicker } from '@svgrid/grid'
```
## Example
`SvDateTimePicker` composes [SvCalendar](https://svgrid.com/docs/help/ui-components/sv-calendar/) and
[SvTimePicker](https://svgrid.com/docs/help/ui-components/sv-time-picker/) behind tabs, over the headless
`createDateTimePicker` core (value math, parse/format, clamping, dropdown and tab
state). The component keeps the render-only concerns - the portalled popover
positioning, DOM refs, and outside-click / reposition listeners - so the dropdown
is never clipped by the grid's scroll container. It carries the shared editor
contract (label, hint, error validation, RTL) via `SvField`, and is the editor
SvGrid mounts for a `datetime` cell.
> Live demo: Date-time picker - https://svgrid.com/demos/252-datetimepicker/
```svelte
(value = d)}
/>
```
## Props
`SvDateTimePicker` extends `SvEditorProps` (`disabled`, `readonly`, `required`,
`invalid`, `error`, `label`, `hint`, `dir`, `name`, `id`, `ariaLabel`).
With a `name`, a form posts the local day (`2026-10-16`) when
`dropDownDisplayMode` is `'calendar'`, the local time (`14:30`) when it is
`'time'`, and the ISO instant (`toISOString()`) when it picks both.
Its own props:
| Prop | Type | Default | Description |
| --------------------- | ---------------------------------------- | -------------------- | ----------------------------------------------------------------- |
| `value` | `DateTimeValue` | `null` | A `Date`, parseable string, or epoch ms. |
| `onChange` | `(value: Date \| null) => void` | - | Fires on every value change. |
| `onCommit` | `(value: Date \| null) => void` | - | Value finalized (Enter, blur, single-date pick). Grid saves here. |
| `onCancel` | `() => void` | - | Escape / dismiss without committing (grid cancels the edit). |
| `formatString` | `string` | `yyyy-MM-dd HH:mm` | Display / parse mask (token engine). |
| `min` / `max` | `DateLike \| null` | `null` | Bounds; the value is clamped into range. |
| `nullable` | `boolean` | `true` | Allow clearing to `null` (shows a clear button). |
| `placeholder` | `string` | `Select date & time` | Empty-field placeholder. |
| `locale` | `string` | navigator | BCP-47 locale for names and formatting. |
| `firstDayOfWeek` | `number` | `0` | `0` = Sunday .. `6` = Saturday (passed to the calendar). |
| `weekNumbers` | `boolean` | `false` | Show the calendar's week-number column. |
| `hourFormat` | `12-hour` \| `24-hour` | `24-hour` | Clock format for the TIME tab. |
| `minuteInterval` | `number` | `1` | Minute snap step for the TIME tab. |
| `dropDownDisplayMode` | `both` \| `calendar` \| `time` | `both` | Which tabs the dropdown shows. |
| `spinButtons` | `boolean` | `false` | Up/down buttons that bump the value by `stepMinutes`. |
| `stepMinutes` | `number` | `1` | Increment for the spin buttons. |
| `autoOpen` | `boolean` | `false` | Open the dropdown as soon as the field is focused. |
| `block` | `boolean` | `false` | Stretch the field to fill its container (100% width); grid cell editor. |
| `animate` | `boolean` \| `slide` \| `fade` | `false` | Animate the calendar's month / drill navigation. |
| `messages` | `Partial` | - | Override the tab / dialog / aria strings. |
### Helper types
- `DateTimeValue = Date | string | number | null`
- `DropDownDisplayMode = 'both' | 'calendar' | 'time'`
## Examples
### Date-only or time-only fields
Drop a tab with `dropDownDisplayMode` and match the mask, so one component covers
`date`, `time`, and `datetime` columns. This demo shows five field shapes on one
form:
> Live demo: Date-time picker - form fields - https://svgrid.com/demos/259-datetimepicker-forms/
```svelte
```
### Typed input with validation
Text is parsed on blur / Enter; input that doesn't fit the mask reverts, and the
value is clamped to `min` / `max`. Wire `invalid` / `error` through the editor
contract for a described error:
```svelte
(start = d)}
/>
```
### Spin buttons for fine nudges
Turn on `spinButtons` and set `stepMinutes` for keyboard-free increments -
useful for timers and scheduling grids:
```svelte
(value = d)} />
```
### In-grid cell editor
This is the editor SvGrid mounts for a `datetime` cell. Turn on `autoOpen` so the
dropdown appears the moment the field is focused, and map `onCommit` / `onCancel`
to save or cancel the edit:
```svelte
save(d)}
onCancel={() => cancel()}
/>
```
Tip: `onChange` fires on every edit, but `onCommit` fires only when the value is
finalized (Enter, blur, or a single-date pick) - persist on `onCommit`, preview
on `onChange`.
## Accessibility
- Built on `SvField`, so `label`, `hint`, and `error` are wired via
`for` / `aria-describedby`; `invalid` sets `aria-invalid`.
- The dropdown is a `role="dialog"`; the toggle carries an accessible open label
and the tabs are a `role="tablist"`.
- The popover portals to `` and repositions on scroll / resize, so it is
never clipped inside a scrolling grid.
- `onCommit` / `onCancel` map Enter and Escape for in-grid cell editing.
## More examples
### Date-time picker - headless
Styled SvDateTimePicker (portalled dropdown) and a custom masked field, sharing one value.
> Live demo: Date-time picker - headless - https://svgrid.com/demos/278-headless-datetimepicker/
## In a form
The shared field props behave the same on every editor: `label` names it, `hint` explains it, and `error` plus `invalid` mark it - which is why a validated form does not need per-component handling.
```svelte
```
## Disabled and read-only
Disabled takes the control out of the tab order; read-only keeps it focusable and copyable. Reach for read-only when the value still matters to the reader.
```svelte
```
## See also
- [Date & time overview](https://svgrid.com/docs/help/ui-components/date-time/) - the whole family at a glance.
- [SvCalendar](https://svgrid.com/docs/help/ui-components/sv-calendar/) / [SvTimePicker](https://svgrid.com/docs/help/ui-components/sv-time-picker/) - the two pickers it composes.
- [SvDateRangeInput](https://svgrid.com/docs/help/ui-components/sv-date-range-input/) - the range sibling.
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/sv-date-time-picker/ . All docs: https://svgrid.com/llms.txt