Bridge UI

TimeField

Form field that opens a wall-clock TimePicker in an overlay (auto by default: menu on desktop, bottom drawer on mobile).

Introduction

TimeField is a form control that opens a TimePicker in an overlay (auto by default: menu on desktop, bottom drawer on mobile): a label, a read-only trigger input, and helper or error text, all wrapped in FormField chrome. It uses the semantic clock icon by default at the inline end of the field.

The trigger commits a wall-clock Date (hours and minutes by default; include seconds with showSeconds) rather than a full date. Use DateTimeField when both a date and a time are required, or TimeRangeField when users need to pick a start and end time together.

Import

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

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 trigger input is read-only; clicking or focusing it opens the picker menu.

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 trigger.
  • readonly — keeps the value visible and focusable but not editable; the 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.

Ampm

Set ampm to use a 12-hour clock with a dedicated AM/PM column in the picker.

Interval

Use interval to control the minute step between selectable options (default 1).

Show seconds

Set showSeconds to add a seconds column to the picker 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

Use minTime and maxTime to limit the selectable range, or disableTimes to exclude specific times.

Selectable times are limited to 09:00–18:00.

Selectable times are limited to 09:00–18:00.

Set showFooter to render Cancel / Apply actions on the nested picker. 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 TimePicker

TimePicker is the inline picker TimeField opens in an overlay (auto by default: menu on desktop, bottom drawer on mobile). Use it directly for toolbars, inline forms, or any layout where a floating menu is not desired. The same footer slot replaces Cancel / Apply: apply() commits (and closes an overlay), cancel() discards.

TimePanel

TimePanel is the scrollable hour / minute (/ second / AM·PM) column building block used inside TimePicker. Pass showSeconds to include a seconds column. Use it directly for fully custom compositions.

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 time.

Pick a valid time.

TimeRangeField, DateTimeField, TextField

Accessibility

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

  • 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 trigger is read-only; the picker menu opens on click or focus and closes on Escape.

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

Anatomy

TimeField composes FormField around a read-only trigger input, opening a TimePicker inside 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 trigger showing the formatted time
│   └── End adornment — clock icon (default) or custom endIcon
├── Menu — opens on trigger click, focus, or Escape to close
│   └── TimePicker
│       └── TimePanel — hour / minute (/ AM·PM) columns
└── Footer — description (helper text) or error message

API

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

TimeField-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.
interval number 1 Minute step between options.
minTime Date — Earliest selectable time.
maxTime Date — Latest selectable time.
overlay FieldOverlayMode "auto" Overlay shell: menu, modal, drawer, or auto.
disableTimes Date[] — Times that cannot be selected.
showFooter boolean false (true for modal/drawer when unset) Shows Cancel / Apply on the nested picker.
timeZone string — IANA time zone.
placeholder string — Native attribute forwarded to the trigger input.

Events

Event Payload Description
@apply — Emitted when Apply is pressed (showFooter).
@cancel — Emitted when Cancel is pressed (showFooter).
@change Date | null Emitted when the time changes.
@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: Date | null) Called when the time 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 and the nested picker.
size FormFieldSize "md" Typography and control sizing.
rounded FormFieldRounded "md" Border radius of the field control and the nested picker.
startIcon IconSource — Icon at the inline start.
endIcon IconSource "clock" 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 TimeFieldClasses — Class overrides for field / input regions.
customProps TimeFieldCustomProps — Props for each part, plus menu, modal, drawer (forwarded to the overlay shell) and timePicker (forwarded to the nested TimePicker).
slots TimeFieldSlots — React slots. Vue: #label, #corner, default, #description, #errorMessage, #start, #end, #footer.