Skip to content
BookMD
UI
Language:en Author:AtomForge

UI

DateTimePicker

A combined date and time form control. It uses DateTimePopover internally and returns a local JavaScript Date | null.

Import

import { DateTimePicker, DateTimePickerBody, DateTimePopover } from '@atom-forge/ui';

Props

Prop Type Default Description
value Date | null null Bindable selected date and time.
format (date: Date) => string en-US date/time Custom display formatter.
placeholder string 'Select date and time' Text shown when no value is selected.
disabled boolean false Disables the picker.
clearable boolean false Shows a clear button.
min Date — Earliest selectable date (inclusive).
max Date — Latest selectable date (inclusive).
seconds boolean false Enables seconds in the selected time.
round false | 0 | 5 | 10 | 15 | 20 | 30 | number[] false Rounds or snaps minutes.
compact boolean false Compact size. Mutually exclusive with small.
small boolean false Small size. Mutually exclusive with compact.
class string — Additional CSS classes for the trigger element.
Component Description
DateTimePickerBody Combined date and time body without a trigger or overlay.
DateTimePopover Anchored popover around DateTimePickerBody with a full-width confirmation footer.
DateTimePicker Form control that uses DateTimePopover internally.

Popover Behavior

  • Popovers close on outside click and Escape.
  • Confirmation is explicit through the full-width footer button.
  • The default confirmation label is OK; pass confirmLabel to localize it.
  • onconfirm may be async; the footer shows loading while pending.
  • When a date is selected without changing the time, the time portion defaults to local midnight.

Usage

<DateTimePicker bind:value={startsAt} min={new Date()} round={5} clearable />

Action popover

<DateTimePopover value={startsAt} confirmLabel="Save" onconfirm={saveStartsAt}>
  {#snippet trigger(open, isOpen)}
    <Button secondary outline label="Choose date and time" onclick={open} aria-expanded={isOpen} />
  {/snippet}
</DateTimePopover>

When to use

Use for a nullable local date/time, not a date-only value or timezone-aware scheduling model.

Alternatives

Use DatePicker for a calendar date or TimePicker for an independent time string. DateTimePickerBody supports inline composition.

Setup and behavior

Render DateTimePicker and DateTimePopover below Root. Bind Date | null; desktop edits commit only after OK, while coarse-pointer datetime-local writes immediately. The desktop calendar treats min/max as day bounds and does not constrain the time spinner to exact timestamps. The native input receives timestamp min/max but does not apply round. Validate exact limits and timezone conversion in the application. No timezone selection or range mode is provided. Default formatting omits seconds even when seconds is enabled; supply format to display them.