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.

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:

<script lang="ts">
  import { SvDateTimePicker } from '@svgrid/grid'

  // The bound value behind each example below.
  let cell = $state<Date | null>(null)
</script>

import { SvDateTimePicker } from '@svgrid/grid'

Example

SvDateTimePicker composes SvCalendar and SvTimePicker 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.

Open the live example: Date-time picker (Date & Time)

<script lang="ts">
  import { SvDateTimePicker } from '@svgrid/grid'
  let value = $state<Date | null>(new Date())
</script>

<SvDateTimePicker
  {value}
  formatString="yyyy-MM-dd HH:mm"
  dropDownDisplayMode="both"
  min={new Date(2020, 0, 1)}
  nullable
  spinButtons
  onChange={(d) => (value = d)}
/>

Props

SvDateTimePicker extends SvEditorProps (disabled, readonly, required, invalid, error, label, hint, dir, name, id, ariaLabel). 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<DateTimeMessages>`	-	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:

Open the live example: Date-time picker - form fields (Date & Time)

<SvDateTimePicker dropDownDisplayMode="calendar" formatString="yyyy-MM-dd" />
<SvDateTimePicker dropDownDisplayMode="time" formatString="HH:mm" hourFormat="12-hour" />

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:

<SvDateTimePicker
  label="Starts"
  min={new Date()}
  invalid={!!err}
  error={err}
  onChange={(d) => (start = d)}
/>

Spin buttons for fine nudges

Turn on spinButtons and set stepMinutes for keyboard-free increments - useful for timers and scheduling grids:

<SvDateTimePicker spinButtons stepMinutes={15} onChange={(d) => (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:

<SvDateTimePicker
  value={cell}
  autoOpen
  dropDownDisplayMode="both"
  onCommit={(d) => 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 <body> 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.

Open the live example: Date-time picker - headless (Headless Editors)

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.

<script lang="ts">
  import { SvDateTimePicker } from '@svgrid/grid'

  let cell = $state<Date | null>(null)
</script>

<SvDateTimePicker
  value={cell}
  label="Label"
  hint="A short hint"
  required
/>

<SvDateTimePicker
  value={cell}
  label="Label"
  error="Something is wrong"
  invalid
/>

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.

<script lang="ts">
  import { SvDateTimePicker } from '@svgrid/grid'

  let cell = $state<Date | null>(null)
</script>

<SvDateTimePicker value={cell} disabled />

<SvDateTimePicker value={cell} readonly />

Live examples

Date-time picker - SvDateTimePicker: a formatted input plus a portalled dropdown with DATE / TIME tabs (calendar + clock). Type a masked value or pick it; invalid input reverts. min/max, nullable, 12/24-hour, spin buttons. The SvGrid datetime cell editor, standalone in any SvGrid app.
Date-time picker - form fields - SvDateTimePicker in five real shapes on one form: date-only, time-only, date+time, 12-hour with spin buttons, and a min/max-constrained field. Masked inputs (type or pick), portalled dropdowns, animated calendars. The SvGrid datetime cell editor, standalone.
Date-time picker - headless - Styled SvDateTimePicker (portalled dropdown) and a custom masked field, sharing one value.

SvGrid UI Components Tips and Tricks: Svelte 5 Buttons, Inputs, Tree, Forms - Practical tips for the SvGrid UI component kit - SvButton states, a Cmd+K command palette, a virtualized searchable tree, schema-driven forms, a parsing date/time field, and the shared field contract - each with a code snippet.