Browse docs

DateTimePicker

DateTimePicker is a form-connected date and time field: a read-only trigger that opens a popover combining a Calendar with a time list. Pick a date, then a time. It integrates with DashForm and RBAC automatically.

The stored value is a naive ISO datetime — "YYYY-MM-DDTHH:mm" — or null. No seconds, no time zone.

DateTimePicker was rebuilt in @dashforge/tw 0.10.0-beta as a fully custom component on the headless @dashforge/calendar-core engine, replacing the previous native-input version. For a date-only field use DatePicker; for time-only use TimePicker.

Quick Start

tsx

import { DashForm } from '@dashforge/forms';
import { DateTimePicker } from '@dashforge/tw';

<DashForm onSubmit={(data) => console.log(data)}>
  <DateTimePicker
    name="appointment"
    label="Appointment"
    rules={{ required: 'Please pick a date and time' }}
  />
</DashForm>

The committed value is a string: "2026-05-15T10:00".

Examples

A basic field — open the popover, click a date (the popover stays open), then a time (the popover closes).

Appointment

import { DateTimePicker } from '@dashforge/tw';

<DateTimePicker name="appointment" label="Appointment" />

Constrained dates

minDate / maxDate bound the calendar; stepMinutes sets the time-list granularity.

Appointment slot

import { DateTimePicker } from '@dashforge/tw';

<DateTimePicker
  name="slot"
  label="Appointment slot"
  minDate="2026-05-01"
  maxDate="2026-05-31"
  stepMinutes={30}
  defaultValue="2026-05-15T10:00"
/>

API

Prop	Type	Default	Description
`name`	`string`	—	Field name — the bridge registration key. Required.
`label`	`ReactNode`	—	Field label.
`helperText`	`ReactNode`	—	Hint text below the control.
`rules`	`RegisterOptions`	—	Validation rules forwarded to the form bridge.
`required`	`boolean`	`false`	Adds the label asterisk.
`error`	`boolean`	—	Explicit error state (overrides the bridge's auto error).
`disabled`	`boolean`	`false`	Disables the field.
`placeholder`	`string`	—	Shown when no value is selected.
`layout`	`'stacked' \| 'inline'`	`'stacked'`	Label / control layout.
`value`	`string \| null`	—	Controlled value (`"YYYY-MM-DDTHH:mm"`).
`defaultValue`	`string \| null`	—	Uncontrolled initial value.
`onChange`	`(value: string \| null) => void`	—	Fired with the new datetime.
`minDate` / `maxDate`	`ISODate`	—	Calendar bounds (inclusive).
`disabledDates`	`ISODate[]`	—	Explicit list of disabled dates.
`isDateDisabled`	`(date: ISODate) => boolean`	—	Predicate disabling arbitrary dates.
`weekStartDay`	`WeekDay`	`0`	First-column weekday of the calendar.
`locale`	`string`	`'en-US'`	BCP-47 locale for the calendar + display format.
`stepMinutes`	`number`	`30`	Step between time-list options, in minutes.
`hour12`	`boolean`	`false`	Render the time list in 12-hour notation.
`visibleWhen`	`(engine: Engine) => boolean`	—	Reactive visibility predicate.
`access`	`AccessRequirement`	—	RBAC access requirement.
`fullWidth`	`boolean`	`false`	Stretches the field to its container width.
`sx`	`string`	—	Tailwind class override for the root element.
`slotProps`	`DateTimePickerSlotProps`	—	Per-slot `className` overrides.
`testId`	`string`	—	Test id applied to the field root.

Notes

Naive "YYYY-MM-DDTHH:mm" storage — no seconds, no time zone.
Pick flow. Picking a date keeps the popover open (a time is still needed); picking a time completes the value and closes the popover.
Breaking change (0.10.0-beta): the legacy native-input DateTimePicker is gone. The mode prop is removed — use DatePicker / TimePicker for date-only / time-only; min / max / step / onValueChange are now minDate / maxDate / stepMinutes / onChange. The isoToInputValue export was also removed.

Capabilities

Controlled

tsx

<DateTimePicker
  value={appointment}
  onChange={(v) => setAppointment(v)}
  label="Appointment"
/>

React Hook Form ready

Inside DashForm the field registers automatically — validation, error gating, and touch tracking flow through the bridge.

RBAC access control

tsx

<DateTimePicker
  name="publishAt"
  label="Publish at"
  access={{ resource: 'article', action: 'publish', onUnauthorized: 'hide' }}
/>