DocsComponents

Time picker

Choose a time using the original radial clock face.

Reminder

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/time-picker.json

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

Values are Date objects. Choose format="24hr" or format="ampm" to match your application.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

TimePicker has a controlled Date value. Update it in onChange; there is no defaultValue API. The dialog edits a draft time until confirmation.

The input manages its own opening and dismissal. Changes to active synchronize that state, and onDismiss reports dismissal. format selects the 12-hour or 24-hour clock presentation.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`TimePicker`

Property	Type	Default
`error`	`React.ReactNode`	`—`
`floating`	`boolean`	`—`
`hint`	`React.ReactNode`	`—`
`icon`	`React.ReactNode`	`—`
`label`	`React.ReactNode`	`—`
`multiline`	`boolean`	`—`
`rows`	`number`	`—`
`ref`	`React.Ref<InputHandle>`	`—`
`active`	`boolean`	`false`
`cancelLabel`	`string`	`—`
`format`	`TimeFormat`	`'24hr'`
`inputClassName`	`string`	`—`
`okLabel`	`string`	`—`
`readonly`	`boolean`	`—`
`classNames`	`TimePickerTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`TimePickerTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`value`	`Date`	`—`

Callbacks

Property	Type	Default
`onChange`	`(time: Date, event?: React.MouseEvent<HTMLElement>) => void`	`—`
`onDismiss`	`() => void`	`—`
`onEscKeyDown`	`(event: KeyboardEvent) => void`	`—`
`onOverlayClick`	`MouseEventHandler<HTMLDivElement>`	`—`

Also inherits Omit<Omit<React.InputHTMLAttributes<InputElement>, 'onChange' | 'size'>, 'value' | 'defaultValue' | 'onChange' | 'theme' | 'classNames'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Additional defaults on inherited props: className = ''.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

active
am
amFormat
ampm
button
clock
clockWrapper
container
dialog
disabled
face
hand
header
hours
hoursDisplay
input
inputElement
knob
minutes
minutesDisplay
number
placeholder
pm
pmFormat
separator
small
zoomInEnter
zoomInEnterActive
zoomInExit
zoomInExitActive
zoomOutEnter
zoomOutEnterActive
zoomOutExit
zoomOutExitActive

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/time-picker.

TimePickerTheme

tsx

type TimePickerTheme = Partial<
  Record<
    | 'container'
    | 'active'
    | 'am'
    | 'amFormat'
    | 'ampm'
    | 'button'
    | 'clock'
    | 'clockWrapper'
    | 'dialog'
    | 'disabled'
    | 'face'
    | 'hand'
    | 'header'
    | 'hours'
    | 'hoursDisplay'
    | 'input'
    | 'inputElement'
    | 'knob'
    | 'minutes'
    | 'minutesDisplay'
    | 'number'
    | 'placeholder'
    | 'pm'
    | 'pmFormat'
    | 'separator'
    | 'small'
    | 'zoomInEnter'
    | 'zoomInEnterActive'
    | 'zoomInExit'
    | 'zoomInExitActive'
    | 'zoomOutEnter'
    | 'zoomOutEnterActive'
    | 'zoomOutExit'
    | 'zoomOutExitActive',
    string
  >
>;

TimePickerClassNames

tsx

type TimePickerClassNames = TimePickerTheme;

TimePickerProps

tsx

interface TimePickerProps
  extends Omit<InputProps, 'value' | 'defaultValue' | 'onChange' | 'theme' | 'classNames'> {
  active?: boolean;
  cancelLabel?: string;
  format?: TimeFormat;
  inputClassName?: string;
  okLabel?: string;
  onChange?: (time: Date, event?: TimePickerSelectEvent) => void;
  onDismiss?: () => void;
  onEscKeyDown?: TimePickerDialogProps['onEscKeyDown'];
  onOverlayClick?: TimePickerDialogProps['onOverlayClick'];
  readonly?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: TimePickerTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: TimePickerTheme;
  value?: Date;
}

Material guidelines

Use the clock face for selecting a specific time, with separate hour and minute steps and an explicit confirmation.
Choose the 12-hour or 24-hour format to suit the user’s preferences. The application supplies that preference; the component does not infer it automatically.

Material Design 1: Pickers