Bridge UI

DateRangeField

Form field that opens a dual-month DateRangePicker calendar in an overlay (auto by default: menu on desktop, bottom drawer on mobile).

Introduction

DateRangeField is a complete form control: a label, an input that displays the selected range, and a dual-month calendar that opens in an overlay (auto by default: menu on desktop, bottom drawer on mobile). It wraps FormField chrome around a native <input> and an inline DateRangePicker, so you get consistent layout, validation styling, and range selection without assembling those pieces yourself.

For a single date instead of a range, use DateField, which can also select a range via its range prop when you prefer a single-calendar UI.

Import

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

Basic usage

Provide a label and placeholder. Bind the value with value/onChange in React or v-model in Vue—the value is a two-item tuple [start, end] | null. For uncontrolled usage with an initial value, use defaultValue in React or default-value in Vue. Clicking the field opens a menu with two calendars; selecting a start and end day commits the value and closes the menu.

Stored as a [start, end] tuple.

Stored as a [start, end] tuple.

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; the calendar menu does not open.

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

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

Constrain the selectable range with minDate and maxDate. Days outside the bounds are disabled on both calendar panels.

Selectable days limited to Aug 1–28, 2026.

Selectable days limited to Aug 1–28, 2026.

Set showFooter to add Cancel / Apply actions to 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 on the calendar until Apply is pressed.

Selection is a draft on the calendar until Apply is pressed.

Orientation

Set orientation to vertical to stack the two calendar panels instead of showing them side by side—useful in narrow layouts. Default is horizontal.

Calendars stack vertically instead of side by side.

Calendars stack vertically instead of side by side.

DateRangePicker

DateRangePicker is the inline dual-month calendar that DateRangeField opens in an overlay (auto by default: menu on desktop, bottom drawer on mobile). Use it directly when you need an always-visible range calendar without the FormField shell or menu behavior—for example, in a sidebar or a custom popover. Internally, it renders CalendarRange with a shared year/month header.

It supports the same value/onChange, minDate/maxDate, orientation, and showFooter props as DateRangeField, plus standalone-only props like color and disabled. The same footer slot replaces Cancel / Apply: apply() commits (and closes an overlay), cancel() discards.

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

CalendarRange

CalendarRange is the underlying dual-month calendar used by DateRangePicker (and, in turn, DateRangeField). Use it directly when you need finer control—such as a controlled viewDate, hover-preview handling via previewDate/onPreviewDateChange, or custom aside content per panel—without the picker’s Cancel / Apply chrome.

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

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.

Select a valid range.

Select a valid range.

DateRangePicker, DateField, Select

Accessibility

For the field to be accessible, the input must be linked to its label and helper or error text:

  • The label is associated with the input via htmlFor / id, using controlId (auto-generated when omitted).
  • description and errorMessage are linked through aria-describedby on the input.
  • When error is true, the input receives aria-invalid="true".
  • Calendar navigation follows standard keyboard interaction for grid widgets (arrow keys to move between days, Enter/Space to select) across both panels.

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

Anatomy

DateRangeField composes FormField around a native <input> and opens a DateRangePicker in an overlay (auto by default: menu on desktop, bottom drawer on mobile):

FormField (root)
├── Header — label, optional corner text, required indicator
├── Container — variant shell (outline, filled, …)
│   └── Input — read-only text input showing the formatted range
└── Footer — description (helper text) or error message

Menu (opened on click)
└── DateRangePicker — shared year/month header, two calendar panels
    (horizontal or vertical), optionally with Cancel / Apply footer

API

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

DateRangeField-specific

Prop Type Default Description
minDate Date — Earliest selectable date.
maxDate Date — Latest selectable date.
clearable boolean true Whether the value can be cleared.
overlay FieldOverlayMode "auto" Overlay shell: menu, modal, drawer, or auto.
disableDates Date[] — Dates that cannot be selected.
disableMonths number[] — Month indexes that cannot be selected.
disableYears number[] — Years that cannot be selected.
orientation "horizontal" | "vertical" "horizontal" Dual calendar layout forwarded to the picker.
showFooter boolean false (true for modal/drawer when unset) Shows Cancel / Apply on the nested picker.
hideMonths boolean false Hides the shared month selector and month panel.
hideYears boolean false Hides the shared year selector and year panel.
hideWeekdays boolean false Hides weekday labels on both date panels.
hideOutsideDays boolean false Hides days that fall outside the displayed month on both panels.
startOfWeek StartOfWeek 0 First day of the week.
timeZone string — IANA time zone.
classes DateRangeFieldClasses — Classes for field / input regions.
customProps DateRangeFieldCustomProps — Extra props for internal parts (input, menu, modal, drawer, dateRangePicker, …).
slots DateRangeFieldSlots — Named slots (FormField slots + calendar day + footer).

Events

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

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.
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 and the calendar menu panel.
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 FormFieldClasses — Class overrides per part.
customProps FormFieldCustomProps — Props for each part. label accepts Label props (without children); error label colors come from Label.
slots FormFieldSlots — React slots. Vue: #label, #corner, default, #description, #errorMessage, #start, #end.