Bridge UI

DateTimeRangeField

Date and time range picker field with dual calendars, bounds, and AM/PM support.

Introduction

DateTimeRangeField is a complete form control for picking a start and end date-time as a single pair. It wraps FormField chrome around an overlay-based DateTimeRangePicker (auto by default: menu on desktop, bottom drawer on mobile; dual calendars, each with its own time panel), so you get consistent layout, validation styling, and a formatted range display without assembling those pieces yourself.

Use DateTimeRangeField when users pick a window with both a date and a time on each end—bookings, shifts, or event windows. For a single date-time, use DateTimeField. For a date-only range, use the dedicated DateRangeField component.

Import

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

Basic usage

Provide a label and placeholder. Bind the value—a DateRangeValue tuple of [start, end] date-times—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.

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 both time panels 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, for both ends of the range.

Show seconds

Set showSeconds to add a seconds column to both time panels 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. The bounds apply to both ends of the range.

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.

Orientation

Use orientation to control the dual calendar layout inside the picker: "horizontal" (default) places the two Calendar + Time pairs side by side; "vertical" stacks them. Year stays on the left and nav on the right, with month selectors inward from the header midpoint. Opening month or year view covers the TimePanels with an opaque overlay so the picker height stays put. Month and year views follow the start calendar.

Standalone DateTimeRangePicker

Use DateTimeRangePicker directly—combining CalendarRange with a time panel beside each month—when you need the dual calendars and times inline, without FormField chrome or a menu trigger. Year sits on the left and nav on the right; month selectors sit inward from the header midpoint.

DateTimeRangePicker accepts the same ampm, interval, showSeconds, minDate/maxDate, minTime/maxTime, orientation, and showFooter props as DateTimeRangeField, plus standalone-only color, rounded, error, and fill props for the calendars 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). Drawer overlays scroll horizontally when dual calendars or time columns overflow, with bridge-scroll-fade-x on the inner scroller. See Scroll utilities. 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.

DateTimeField, DateRangeField

Accessibility

For the field to be accessible, the trigger input must be linked to its label and helper or error text, and both calendars and time panels 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".
  • Each calendar panel follows WAI-ARIA grid conventions for date navigation; time panels are keyboard-navigable and expose 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

DateTimeRangeField composes FormField around a trigger input and an overlay-based dual 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 start → end range input, opens the picker menu
├── Menu — DateTimeRangePicker (CalendarRange header, two Calendar + TimePanel pairs), optional Cancel / Apply footer
└── Footer — description (helper text) or error message

API

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

DateTimeRangeField-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.
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.
orientation "horizontal" | "vertical" "horizontal" Dual calendar layout forwarded to the picker.
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 DateTimeRangeFieldClasses — 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 DateTimeRangeFieldCustomProps — Props for each part, including the nested dateTimeRangePicker. 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 DateTimeRangeFieldSlots — 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 DateRangeValue | null Emitted when the range 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 DateRangeValue | null Called when the range changes.
onClose — Called when the menu closes.
onOpen — Called when the menu opens.