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.

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.

Basic usage

<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, size, 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.
animate boolean | slide | fade false Animate the calendar's month / drill navigation.
messages Partial<DateTimeMessages> - Override the tab / dialog / aria strings.

Helper types

Patterns

Date-only or time-only fields

Drop a tab with dropDownDisplayMode and match the mask, so one component covers date, time, and datetime columns:

<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

See also