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.

The input is read-only by default (picker only). Set editable to unlock typing. The field does not parse or commit typed text — handle that in your own component if needed.

Use description for helper text below the field. When error and errorMessage are both set, the description is hidden unless showDescriptionOnError.

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.

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.

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.

DateTimePicker accepts the same ampm, interval, showSeconds, minDate/maxDate, minTime/maxTime, and showFooter props as DateTimeField, plus standalone-only color, rounded, error, and fill 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). When unset, fill defaults to true for drawer overlays (false for menu / modal). 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.

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
default-value	Date \| null	—	Initial value for uncontrolled usage (without v-model).
v-model	Date \| null	—	Two-way binding for the date-time value.

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

DateTimeField-specific

Prop	Type	Default	Description
ampm	boolean	false	Uses a 12-hour clock with an AM/PM column.
clearable	boolean	false	Whether the value can be cleared.
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.
editable	boolean	false	Unlocks the input. Does not parse or commit typed text.
fill	boolean	—	Fills the overlay width. Unset: true for drawer, false for menu / modal.
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.
showSeconds	boolean	false	Shows seconds in the panel and formatted value.
startOfWeek	StartOfWeek	0	First day of the week.
timeZone	string	global.timeZone	IANA time zone for the UI wall clock. The value Date is a UTC instant.

Inherited from FormField

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

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.