Components

DateTimePicker

A date, time, datetime, and range picker. It shows a calendar popover on desktop and an iOS-style inertial wheel sheet on touch devices — from the same instance.

Overview

Point DateTimePicker at a text input. It binds the input as a combobox, opens on focus or click, writes a formatted display string back to the field, and keeps a machine-readable value in data-dt-value for forms.

new UISuite.DateTimePicker("#date", { mode: "date" });

Basic date

mode: "date"

Features

Four modes: date, time, datetime, and range.
Automatic desktop popover vs. touch bottom sheet.
12- or 24-hour clock with configurable hour and minute steps.
Min/max bounds and arbitrary disabled-date predicates.
Locale-aware month, weekday, and formatting via Intl.
Full keyboard navigation on desktop calendars.

Initialization examples

Datetime, 12-hour

new UISuite.DateTimePicker("#datetime", {
  mode: "datetime",
  use24Hour: false,
  minuteStep: 5,
  displayFormat: "DD/MM/YYYY hh:mm A",
});

Range, weekends disabled

new UISuite.DateTimePicker("#range", {
  mode: "range",
  displayFormat: "MMM D",
  disabledDates: (date) => date.getDay() === 0 || date.getDay() === 6,
  onChange: (val) => console.log(val.start, val.end),
});

Options

Option	Type	Default	Description
`mode`	`string`	`"date"`	`"date"` · `"time"` · `"datetime"` · `"range"`
`locale`	`string`	`navigator.language`	BCP-47 locale used for labels and formatting.
`displayFormat`	`string`	mode-based	Tokens: `YYYY MM DD HH hh mm A`, plus `MMM`/`D`.
`firstDayOfWeek`	`number`	`1`	0 = Sunday, 1 = Monday.
`minDate` / `maxDate`	`Date\|string`	`null`	Selectable bounds; values are clamped.
`disabledDates`	`Date[]\|string[]\|fn`	`null`	Array of dates or a `(date) => boolean` predicate.
`minuteStep`	`number`	`1`	Granularity of the minute control.
`hourStep`	`number`	`1`	Granularity of the hour control.
`use24Hour`	`boolean`	`true`	24-hour clock, or 12-hour with AM/PM.
`inline`	`boolean`	`false`	Render an always-open calendar after the input.
`touchUi`	`"auto"\|boolean`	`"auto"`	Force or disable the touch wheel sheet.
`autoClose`	`boolean`	`true`	Close after a complete selection.
`defaultValue`	`Date\|string`	`null`	Initial value when the input is empty.
`theme`	`"auto"\|"light"\|"dark"`	`"auto"`	Token theme mode.
`onChange`	`function`	—	Called with the new value.
`onOpen` / `onClose`	`function`	—	Open/close lifecycle callbacks.

Methods

Method	Returns	Description
`getValue()`	`Date \| {start,end} \| null`	Current value; an object in `range` mode.
`setValue(val, silent?)`	`this`	Set the value; pass `true` to skip the change event.
`open()` / `close()`	`void`	Programmatically toggle the surface.
`setTheme(mode)`	`this`	Switch theme at runtime.
`on(event, fn)` / `off(...)`	`disposer`	Subscribe to events.
`destroy()`	`void`	Restore the input and remove all listeners.

Events

Subscribe with on() or the matching option callback. The bound input also dispatches a native change event plus a dt:change CustomEvent carrying the value in detail.

Event	Payload	Fires when
`change`	`Date \| {start,end}`	The value changes.
`open`	`—`	The surface opens.
`close`	`—`	The surface closes.

States & variants

Live examples of every mode. Resize the window to a phone width to switch any of them to the touch wheel sheet.

Time only

mode: "time"

Date & time (12h)

mode: "datetime" · 12h · step 5

Date range

mode: "range" · weekends off

Bounded date

minDate / maxDate

Inline calendar

With inline: true the calendar renders directly in the page and stays open.

Always-open calendar

inline: true

The input is a role="combobox" with aria-haspopup="dialog" and a live aria-expanded state.
Calendar days are role="gridcell" buttons with full date labels for screen readers.
Arrow keys move by day/week, PageUp/PageDown by month, Enter selects, and Escape closes.
The touch sheet is a focus-trapped modal dialog. See Accessibility.

Common mistakes

Forgetting the stylesheet

The picker renders to a body portal. Without ui-suite.css loaded globally, the panel appears unstyled. Load the CSS once at the document level, not scoped to a component.

Reading input.value for logic. That holds the human display string. Use getValue() or the data-dt-value attribute for machine values.
Expecting a string in range mode. getValue() returns { start, end } with Date objects.
Passing minuteStep that doesn't divide 60. Use values like 5, 10, 15, or 30 for an even wheel.