Bridge UI

DateTimeField

Date and time picker field with FormField chrome, bounds, and AM/PM support.

Introduction

DateTimeField is a complete form control that combines a text input with a dropdown DateTimePicker: a label, formatted input, and helper or error text in one component. It wraps FormField chrome around an overlay-based picker (auto by default: menu on desktop, bottom drawer on mobile; Calendar + TimePanel), so you get consistent layout, validation styling, and keyboard-friendly display without assembling those pieces yourself.

Use DateTimeField when a single value needs both a date and a time. For date-only or time-only input, use dedicated DateField and TimeField components instead—each follows the same FormField pattern with a focused picker. For a start/end pair, see DateTimeRangeField.

Import

import { DateTimeField } from "@bridge-ui/vue/Components/DateTimeField";
import { DateTimeField } from "@bridge-ui/react/Components/DateTimeField";

Basic usage

Provide a label and placeholder. Bind the value with value/onChange in React or v-model in Vue. For uncontrolled usage with an initial value, use defaultValue in React or default-value in Vue. The field shows the formatted date and time and opens a DateTimePicker in an overlay (auto by default: menu on desktop, bottom drawer on mobile) when activated.

Form props

Standard form attributes are supported through inherited FormField props:

  • required — shows a red asterisk on the label. Pair with the native required attribute when validating with HTML forms.
  • disabled — prevents interaction and applies disabled styling to the field shell and input.
  • readonly — keeps the value visible and focusable but not editable, and does not open the picker.

Use description for helper text below the field. When error is set, the description is hidden and errorMessage is shown instead.

AM/PM

Set ampm to display and edit time with a 12-hour clock and an AM/PM column, instead of the default 24-hour format.

Interval

Control the minute step between selectable time options with interval (default 1). For example, interval={15} only offers times on the quarter hour.

Show seconds

Set showSeconds to add a seconds column to the time panel and include seconds in the formatted value.

Variants

Control the field shell appearance with the variant prop. Available variants: outline (default), filled, notched, stacked, and underlined.

Sizes

Control the field size with the size prop. Available sizes: 2xs, xs, sm, md (default), lg, xl, and 2xl.

Bounds

Restrict selectable dates with minDate / maxDate, and selectable times with minTime / maxTime. Dates and times outside the allowed range render disabled in the picker.

Days limited to Aug 1–28, 2026, and times to 9 AM–6 PM.

Days limited to Aug 1–28, 2026, and times to 9 AM–6 PM.

Set showFooter to render Cancel / Apply actions on the nested picker. The selection is a draft until Apply is pressed; Cancel discards it and closes. When unset, showFooter defaults to true for modal / drawer overlays (false for menu). A custom footer slot replaces Cancel / Apply: call apply() to commit and close, or cancel() to discard and close.

Selection is a draft until Apply is pressed.

Selection is a draft until Apply is pressed.

Standalone DateTimePicker

Use DateTimePicker directly—combining a Calendar and TimePanel side by side into a single Date instant—when you need the calendar and time inline, without FormField chrome or a menu trigger.

SunMonTueWedThuFriSat
SunMonTueWedThuFriSat

DateTimePicker accepts the same ampm, interval, showSeconds, minDate/maxDate, minTime/maxTime, and showFooter props as DateTimeField, plus standalone-only color and rounded props for the calendar and time tiles. The same footer slot replaces Cancel / Apply: apply() commits (and closes an overlay), cancel() discards.

Overlay

Use the overlay prop to choose the picker shell: auto (default), menu, modal, or drawer. auto uses menu on desktop and a bottom drawer on mobile. When unset, showFooter defaults to true for modal / drawer overlays (false for menu). Apply commits and closes; Cancel discards and closes.

Validation

Set error and errorMessage to show invalid styling and an error message below the field. Use required to show a red asterisk on the label.

Pick a valid date and time.

Pick a valid date and time.

DateField, TimeField, DateTimeRangeField

Accessibility

For the field to be accessible, the trigger input must be linked to its label and helper or error text, and the picker must be reachable by keyboard:

  • The label is associated with the trigger via htmlFor / id, using controlId (auto-generated when omitted).
  • description and errorMessage are linked through aria-describedby on the trigger.
  • When error is true, the trigger receives aria-invalid="true".
  • The calendar panel follows WAI-ARIA grid conventions for date navigation; the time panel is keyboard-navigable and exposes AM/PM as a toggle when ampm is set.

Provide a stable controlId when rendering client-only so labels associate correctly on first paint.

Anatomy

DateTimeField composes FormField around a trigger input and an overlay-based picker (auto by default: menu on desktop, bottom drawer on mobile):

FormField (root)
├── Header — label, optional corner text, required indicator
├── Container — variant shell (outline, filled, …)
│   └── Trigger — formatted date-time input, opens the picker menu
├── Menu — DateTimePicker (Calendar + TimePanel), optional Cancel / Apply footer
└── Footer — description (helper text) or error message

API

Prop Type Default Description
v-model Date | null — Two-way binding for the date-time value.
default-value Date | null — Initial value for uncontrolled usage (without v-model).
Prop Type Default Description
value Date | null — Controlled date-time value. Use with onChange.
defaultValue Date | null — Initial value for uncontrolled usage.
onChange (value: Date | null) => void — Called when the value changes.

DateTimeField-specific

Prop Type Default Description
ampm boolean false Uses a 12-hour clock with an AM/PM column.
clearable boolean true Whether the value can be cleared.
showSeconds boolean false Shows seconds in the panel and formatted value.
defaultView CalendarView "date" Initial calendar panel view.
disableDates Date[] — Dates that cannot be selected.
disableMonths number[] — Month indexes that cannot be selected.
disableTimes Date[] — Times that cannot be selected.
disableYears number[] — Years that cannot be selected.
hideMonths boolean false Hides month navigation / panel.
hideOutsideDays boolean false Hides days that fall outside the displayed month.
hideWeekdays boolean false Hides weekday labels.
hideYears boolean false Hides year navigation / panel.
interval number 1 Minute step between time options.
maxDate Date — Latest selectable date.
maxTime Date — Latest selectable time.
minDate Date — Earliest selectable date.
minTime Date — Earliest selectable time.
overlay FieldOverlayMode "auto" Overlay shell: menu, modal, drawer, or auto.
showFooter boolean false (true for modal/drawer when unset) Shows Cancel / Apply on the nested picker.
startOfWeek StartOfWeek 0 First day of the week.
timeZone string — IANA time zone.

Inherited from FormField

Prop Type Default Description
label string — Primary label text above the control.
description string — Helper text below the control (hidden when invalid).
corner string — Secondary label text at the inline end of the header row.
required boolean false Shows a red asterisk on the label.
disabled boolean false Whether the control is disabled.
readonly boolean false Whether the control is read-only (does not open the picker).
error boolean false Applies invalid styling and hides description.
errorMessage string — Error message below the control.
showErrorIcon boolean true Shows an error icon when invalid.
hideErrorMessage boolean false Does not reserve space for error messages.
variant FormFieldVariant "outline" Visual variant of the field shell.
color FormFieldColor "primary" Color applied to the field control.
size FormFieldSize "md" Typography and control sizing.
rounded FormFieldRounded "md" Border radius of the field control.
start string — Inline-start text inside the field (prefix).
end string — Inline-end text inside the field (suffix).
startIcon IconSource — Icon at the inline start.
endIcon IconSource — Icon at the inline end.
errorIcon IconSource "alert" Icon shown when invalid and showErrorIcon is enabled.
controlId string — Associates labels and helper text with the control. Auto-generated when omitted.
classes DateTimeFieldClasses — Classes for field / input regions.
customProps DateTimeFieldCustomProps — Props for each part, including the nested dateTimePicker. label accepts Label props (without children).
slots DateTimeFieldSlots — Named slots (FormField slots plus calendar day + footer).

Events

Event Payload Description
v-on:apply — Emitted when Apply is pressed (showFooter).
v-on:cancel — Emitted when Cancel is pressed (showFooter).
v-on:change Date | null Emitted when the value changes.
v-on:close — Emitted when the menu closes.
v-on:open — Emitted when the menu opens.
Prop Payload Description
onApply — Called when Apply is pressed (showFooter).
onCancel — Called when Cancel is pressed (showFooter).
onChange Date | null Called when the value changes.
onClose — Called when the menu closes.
onOpen — Called when the menu opens.