structyl

Time Picker API

View component

The full prop reference for the Time Picker component. A MUI-style time field with a 12-hour analog clock panel.

Import

tsx
import { TimePicker } from '@structyl/styled';

Props

TimePicker (default export / TimePickerRoot)

The main time picker component with popover trigger, clock panel, and form integration. Supports controlled and uncontrolled value states.

PropTypeDefault
value#Date | { hour: number; minute: number; second?: number; period?: 'am' | 'pm' } | null | undefined

Controlled time value (Date or TimeValue object)

—
defaultValue#Date | { hour: number; minute: number; second?: number; period?: 'am' | 'pm' } | null | undefined

Initial time value when uncontrolled

—
onChange#(value: Date | null, context: { validationError: TimeValidationError | null; source: 'view' | 'field' | 'shortcut' | 'unknown' }) => void

Fired when time changes via any source (clock, keyboard, etc.)

—
onValueChange#(v: { hour: number; minute: number; second?: number; period?: 'am' | 'pm' }) => void

Fired with TimeValue object when time changes

—
onAccept#(value: Date | null, context: { validationError: TimeValidationError | null; source: 'view' }) => void

Fired when user accepts selection (OK button or closeOnSelect)

—
onError#(error: 'minTime' | 'maxTime' | 'minutesStep' | 'shouldDisableTime' | null, value: Date | null) => void

Fired when validation error state changes

—
disabled#boolean

Disables the picker and all interactions

false
readOnly#boolean

Makes the picker read-only; prevents value changes

false
ampm#boolean

Show AM/PM selector and use 12-hour format (overrides hour12 if provided)

true
hour12#boolean

Use 12-hour format (overridden by ampm if both present)

—
withSeconds#boolean

Include seconds picker clock view

false
closeOnSelect#boolean

Close popover after selecting a value

false
disableOpenPicker#boolean

Disable the trigger button (popover cannot be opened)

false
minTime#Date

Minimum selectable time (validation + clock disabling)

—
maxTime#Date

Maximum selectable time (validation + clock disabling)

—
minutesStep#number

Step for minute picker; disables non-aligned minutes on clock

1
shouldDisableTime#(value: Date, view: 'hours' | 'minutes' | 'seconds' | 'meridiem') => boolean

Custom validation function to disable specific times

—
skipDisabled#boolean

Hide disabled clock positions instead of showing them grayed out

—
timeSteps#{ hours?: number; minutes?: number; seconds?: number }

Increment steps for each clock view

—
referenceDate#Date

Fallback date used when value is a TimeValue object (for time-only conversion)

—
views#('hours' | 'minutes' | 'seconds')[]

Restrict which clock views are available

—
locale#string

BCP 47 locale string for Intl formatting (future)

—
label#React.ReactNode

Visible label above the trigger button

—
placeholder#React.ReactNode

Text displayed when no time is selected

'HH:mm'
helperText#React.ReactNode

Small text below the trigger (e.g. error or hint)

—
required#boolean

Show required asterisk in label

—
error#boolean

Highlight field as erroneous; sets aria-invalid and error text color

—
format#Intl.DateTimeFormatOptions | string

Format for displaying selected time in trigger (e.g. 'HH:mm:ss' or Intl options)

{ timeStyle: 'short' }
id#string

HTML id for the trigger button and label association

—
name#string

HTML name for the trigger button (future form integration)

—
className#string

CSS class for the root wrapper div

—
triggerClassName#string

CSS class for the trigger button

—
contentClassName#string

CSS class for the popover content wrapper

—
columnClassName#string

CSS class for clock number buttons

—
rootProps#React.ComponentPropsWithoutRef<'div'>

Props forwarded to the root div (onClick, style, role, tabIndex, data-*, aria-*)

—
ref#React.Ref<HTMLDivElement>

Ref forwarded to the root wrapper div

—

TimePicker.Root

Primitive headless root that provides context for segments and manages controlled time state. Extends div.

PropTypeDefault
asChild#boolean

Replace with child element (Radix compound pattern)

—
value#Date | { hour: number; minute: number; second?: number; period?: 'am' | 'pm' } | null | undefined

Controlled time value

—
defaultValue#Date | { hour: number; minute: number; second?: number; period?: 'am' | 'pm' } | null | undefined

Initial time value when uncontrolled

—
onChange#(value: Date | null, context: { validationError: TimeValidationError | null; source: 'view' }) => void

Fired when time changes from segments

—
onValueChange#(v: { hour: number; minute: number; second?: number; period?: 'am' | 'pm' }) => void

Fired with TimeValue when time changes

—
onAccept#(value: Date | null, context: { validationError: TimeValidationError | null; source: 'view' }) => void

Fired on closeOnSelect

—
onError#(error: TimeValidationError | null, value: Date | null) => void

Fired when validation error changes

—
disabled#boolean

Disables all segments and interactions

—
readOnly#boolean

Prevents value changes

—
hour12#boolean

Use 12-hour format for hours segment

false
ampm#boolean

Enable AM/PM period segment (overrides hour12)

—
withSeconds#boolean

Include seconds segment

false
closeOnSelect#boolean

Trigger onAccept on value change

false
minTime#Date

Minimum selectable time

—
maxTime#Date

Maximum selectable time

—
minutesStep#number

Minutes increment (>1 fails validation for non-aligned values)

—
disablePast#boolean

Disable times before current moment

—
disableFuture#boolean

Disable times after current moment

—
shouldDisableTime#(value: Date, view: 'hours' | 'minutes' | 'seconds' | 'meridiem') => boolean

Custom validation predicate

—
disableIgnoringDatePartForTimeValidation#boolean

Use full Date context for minTime/maxTime comparison (future)

—
referenceDate#Date

Fallback date for TimeValue to Date conversion

—
label#React.ReactNode

Form label (future)

—
name#string

Hidden input name (future)

—
format#Intl.DateTimeFormatOptions | string

Display format (future)

—
onOpenChange#(open: boolean) => void

Controlled open state change (future)

—
onSelectedSectionsChange#(newValue: 'all' | 'hours' | 'minutes' | 'seconds' | 'meridiem' | number | null) => void

Segment selection changed (future)

—
onViewChange#(view: 'hours' | 'minutes' | 'seconds' | 'meridiem') => void

Clock view changed (future)

—
selectedSections#'all' | 'hours' | 'minutes' | 'seconds' | 'meridiem' | number | null

Controlled selected segment (future)

—
defaultSelectedSections#'all' | 'hours' | 'minutes' | 'seconds' | 'meridiem' | number | null

Initial selected segment (future)

—
view#'hours' | 'minutes' | 'seconds' | 'meridiem'

Controlled active clock view (future)

—
defaultView#'hours' | 'minutes' | 'seconds' | 'meridiem'

Initial active clock view (future)

—
timeSteps#{ hours?: number; minutes?: number; seconds?: number }

Increment steps per view

—
views#('hours' | 'minutes' | 'seconds' | 'meridiem')[]

Allowed clock views (future)

—
inputRef#React.Ref<HTMLInputElement>

Ref to hidden input (future)

—
localeText#Record<string, React.ReactNode>

i18n string overrides (future)

—
locale#string

BCP 47 locale (future)

—
formatDensity#'dense' | 'spacious'

Spacing density for format (future)

—
orientation#'landscape' | 'portrait'

Clock layout orientation (future)

—
readOnlyInput#boolean

Make text non-editable (future)

—
reduceAnimations#boolean

Disable CSS transitions (future)

—
keepOpenDuringFieldFocus#boolean

Keep popover open while segment focused (future)

—
desktopModeMediaQuery#string

Responsive layout trigger (future)

—
disableOpenPicker#boolean

Hide popover trigger icon (future)

—
autoFocus#boolean

Auto-focus first segment (future)

—
ampmInClock#boolean

AM/PM indicator in analog clock (future)

—
skipDisabled#boolean

Skip disabled values on navigation (future)

—
thresholdToRenderTimeInASingleColumn#number

Single-column clock threshold (future)

—
slotProps#Record<string, unknown>

Per-slot prop overrides (future)

—
slots#Record<string, React.ElementType | null | undefined>

Slot component overrides (future)

—
sx#Record<string, unknown> | (theme: unknown) => Record<string, unknown>

MUI system sx prop (future)

—
timezone#string

IANA timezone string (future)

—
viewRenderers#Partial<Record<'hours' | 'minutes' | 'seconds' | 'meridiem', (params: { view: TimePickerView; value: Date | null; onChange: (value: Date | null) => void }) => React.ReactNode | null>>

Custom view render functions (future)

—
open#boolean

Controlled open state (future)

—
defaultOpen#boolean

Initial open state (future)

—
onOpen#() => void

Popover opened (future)

—
onClose#() => void

Popover closed (future)

—
openTo#'hours' | 'minutes' | 'seconds' | 'meridiem'

Initial clock view (future)

'hours'

TimePicker.Segment

Spinbutton for individual time segments (hour, minute, second, period). Responds to arrow keys and keyboard input.

PropTypeDefault
segment#'hour' | 'minute' | 'second' | 'period'

Which segment this spinbutton represents

—
className#string

CSS class for the segment span

—
ref#React.Ref<HTMLSpanElement>

Ref to the span element

—

TimePicker.Separator

Visual separator between segments (e.g. colons between HH:mm:ss).

PropTypeDefault
children#React.ReactNode

Separator content

':'
className#string

CSS class for the span

—
ref#React.Ref<HTMLSpanElement>

Ref to the span element

—

TimePicker.Value

Formatted display of the selected time. Supports Intl.DateTimeFormat or custom format strings.

PropTypeDefault
format#Intl.DateTimeFormatOptions | string

Format spec (Intl options or template string with HH/H/hh/h/mm/m/ss/s/aa/a tokens)

{ timeStyle: 'short' }
locale#string

BCP 47 locale for Intl formatting

—
placeholder#React.ReactNode

Text shown when no time is selected

'Pick a time'

TimePicker.Panel

Standalone analog clock panel for time selection. Used internally by the main TimePicker but can be used independently.

PropTypeDefault
value#Date | null

Current selected time

—
onChange#(value: Date) => void

Fired as user adjusts clock hands

—
onAccept#(value: Date) => void

Fired when OK button clicked

—
onCancel#() => void

Fired when Cancel button clicked

—
ampm#boolean

Show AM/PM toggle

true
withSeconds#boolean

Include seconds clock view

—
minutesStep#number

Minute increment; disables non-aligned positions on clock

—
timeSteps#{ hours?: number; minutes?: number; seconds?: number }

Step size per view

—
minTime#Date

Minimum selectable time (disables positions on clock)

—
maxTime#Date

Maximum selectable time (disables positions on clock)

—
shouldDisableTime#(value: Date, view: 'hours' | 'minutes' | 'seconds' | 'meridiem') => boolean

Custom validation to disable clock positions

—
skipDisabled#boolean

Hide disabled positions instead of showing them faded

—
views#('hours' | 'minutes' | 'seconds' | 'meridiem')[]

Restrict which clock views are available

—
referenceDate#Date

Fallback date when value is undefined

—
columnClassName#string

CSS class for clock number buttons

—
title#React.ReactNode

Header text above clock

'SELECT TIME'
showActions#boolean

Show OK/Cancel buttons

true
className#string

CSS class for the panel wrapper

—
ref#React.Ref<HTMLDivElement>

Ref to the panel div

—

Source code

If you didn't find what you need here, read the component implementation .

structyl — Accessible React Component Library