Dates@knitui/dates

TimePicker

TimePicker is the segmented time input: hours/minutes/(seconds) are kit SpinInput segments, am/pm is the kit AmPmInput, all driven by the use-time-picker controller. The bordered field frame mirrors the kit input recipe and the segments render variant="unstyled". withDropdown opens a Popover holding the TimeControlsList columns (or TimePresets). Supports 12h/24h format, withSeconds, min/max clamping, clearable, label/description/error/required, per-segment xxxInputProps, and per-slot styles sugar (field/segment/colon/dropdown + the wrapper chrome). Cross-platform web + native from one source. Accent + error colours come from the active Tamagui theme.

WebiOSAndroid9 style slots49 own props13 examples

Stories Source Tests Open in Storybook

import { TimePicker } from "@knitui/dates";

Playground

Loading playground…

type

format

size

variant

withSecondsShow the seconds segment.

false

withDropdownOpen a time-controls dropdown on focus.

false

clearableShow a clear button when filled.

false

readOnly

false

disabled

false

Playground

<TimePicker
  type="time"
  format="24h"
  withSeconds={false}
  withDropdown={false}
  clearable={false}
  size="sm"
/>

Examples

Default

Default 24h field with a label.

Loading example…

DefaultSource Storybook

Twelve Hour

12h format adds the am/pm segment.

Loading example…

Twelve HourSource Storybook

With Seconds

With the seconds segment.

Loading example…

With SecondsSource Storybook

Duration

type="duration" allows hours beyond 24 and forces 24h (no am/pm).

Loading example…

DurationSource Storybook

With Dropdown

The time-controls dropdown opens on focus when withDropdown is set.

Loading example…

With DropdownSource Storybook

With Presets

Quick presets shown in the dropdown.

Loading example…

With PresetsSource Storybook

Clearable

Clearable — a clear button appears once a value is set.

Loading example…

ClearableSource Storybook

With Bounds

Bounded — the value clamps into [min, max] when focus leaves the field.

Loading example…

With BoundsSource Storybook

With Validation

Required field with a description and an error message.

Loading example…

With ValidationSource Storybook

States

Read-only and disabled states.

Loading example…

StatesSource Storybook

Sizes

Every size token.

Loading example…

SizesSource Storybook

Slot Styles Sugar

Per-slot styles sugar — props spread onto the composed parts.

Loading example…

Slot Styles SugarSource Storybook

Props

Prop	Type	Default	Description
`amPmInputLabel`	`string \| undefined`	—	`aria-label` of the am/pm input.
`amPmLabels`	`TimePickerAmPmLabels \| undefined`	`{ am: 'AM', pm: 'PM' }`	Labels used for am/pm values.
`amPmRef`	`Ref<TamaguiElement> \| undefined`	—	Ref to the am/pm input host node.
`amPmSelectProps`	`Partial<AmPmInputProps> \| undefined`	—	Props spread onto the am/pm segment (`AmPmInput`); picker wiring wins.
`clearable`	`boolean \| undefined`	`false`	Show a clear button when filled.
`clearButtonProps`	`CloseButtonProps \| undefined`	—	Props passed down to the clear button.
`defaultValue`	`string \| undefined`	—	Uncontrolled default value.
`description`	`ReactNode`	—	Description rendered below the label.
`disabled` system	`boolean \| undefined`	—	If set, the component becomes disabled.
`error`	`ReactNode`	—	Error message / state.
`form`	`string \| undefined`	—	`form` id forwarded to the hidden form input (web only).
`format`	`TimePickerFormat \| undefined` 24h · 12h	`'24h'`	Time format.
`hiddenInputProps`	`TimePickerHiddenInputProps \| undefined`	—	Props forwarded to the hidden form input (web only).
`hoursInputLabel`	`string \| undefined`	—	`aria-label` of the hours input.
`hoursInputProps`	`Partial<SpinInputProps> \| undefined`	—	Props spread onto the hours segment (`SpinInput`) — e.g. a per-segment test id or `aria-label`. Typed to OUR `SpinInput` props (NOT a web-only `React.ComponentProps<'input'>`); the picker's own wiring always wins.
`hoursPlaceholder`	`string \| undefined`	`'--'`	Hours input placeholder.
`hoursRef`	`Ref<TamaguiElement> \| undefined`	—	Ref to the hours input host node.
`hoursStep`	`number \| undefined`	`1`	Number by which hours are incremented/decremented.
`label`	`ReactNode`	—	Field label rendered above the input.
`max`	`string \| undefined`	—	Max possible time value in `hh:mm:ss` format.
`maxDropdownContentHeight`	`number \| undefined`	`200`	Maximum dropdown content height in px.
`min`	`string \| undefined`	—	Min possible time value in `hh:mm:ss` format.
`minHoursDigits`	`number \| undefined`	`2`	Minimum number of hour digits, `type="duration"` only.
`minutesInputLabel`	`string \| undefined`	—	`aria-label` of the minutes input.
`minutesInputProps`	`Partial<SpinInputProps> \| undefined`	—	Props spread onto the minutes segment (`SpinInput`); picker wiring wins.
`minutesPlaceholder`	`string \| undefined`	`'--'`	Minutes input placeholder.
`minutesRef`	`Ref<TamaguiElement> \| undefined`	—	Ref to the minutes input host node.
`minutesStep`	`number \| undefined`	`1`	Number by which minutes are incremented/decremented.
`name`	`string \| undefined`	—	`name` forwarded to the hidden form input so a surrounding `<form>` submits the time (web only).
`onBlur`	`FocusEventHandler<HTMLDivElement> \| undefined`	—	Called once when focus leaves the field.
`onChange`	`((value: string) => void) \| undefined`	—	Called when the value changes.
`onFocus`	`FocusEventHandler<HTMLInputElement> \| undefined`	—	Called once when the field gains focus (not between segments).
`onKeyDown`	`((event: TimePickerKeyDownEvent) => void) \| undefined`	—	Called on keydown anywhere in the field (web: the bubbled segment keydown). Used by `InlineDateTimePicker` to commit on Enter; inert on native.
`pasteSplit`	`TimePickerPasteSplit \| undefined`	`getParsedTime`	Transform a pasted value into time segments.
`popoverProps`	`Partial<Omit<PopoverProps, "children">> \| undefined`	—	Props passed down to the `Popover`.
`presets`	`TimePickerPresets \| undefined`	—	Time presets to display in the dropdown.
`readOnly`	`boolean \| undefined`	—	If set, the value cannot be updated.
`required`	`boolean \| undefined`	—	Mark the field as required (adds the asterisk to the label).
`reverseTimeControlsList`	`boolean \| undefined`	`false`	Reverse the order of the time-controls lists.
`rightSection`	`ReactNode`	—	Content rendered in the right section of the field.
`scrollAreaProps`	`ScrollAreaProps \| undefined`	—	Props passed down to all underlying `ScrollArea` components.
`secondsInputLabel`	`string \| undefined`	—	`aria-label` of the seconds input.
`secondsInputProps`	`Partial<SpinInputProps> \| undefined`	—	Props spread onto the seconds segment (`SpinInput`); picker wiring wins.
`secondsPlaceholder`	`string \| undefined`	`'--'`	Seconds input placeholder.
`secondsRef`	`Ref<TamaguiElement> \| undefined`	—	Ref to the seconds input host node.
`secondsStep`	`number \| undefined`	`1`	Number by which seconds are incremented/decremented.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—
`size` system	`TimePickerSize \| undefined` xs · sm · md · lg · xl	`'sm'`	Field size — the kit input size scale.
`styles` system	`SlotStyles<TimePickerStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching styled part. Slots: `field` / `segment` / `colon` / `dropdown` plus the `Input.Wrapper` chrome (`wrapper` / `label` / `description` / `error` / `required`). The explicit `xxxInputProps` / `popoverProps` / `clearButtonProps` passthroughs win over it.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`type`	`TimePickerType \| undefined` time · duration	`'time'`	TimePicker type: `'time'` for a clock input, `'duration'` for >24h durations.
`value`	`string \| undefined`	—	Controlled value — an `HH:mm[:ss]` string.
`variant` system	`InputVariant \| undefined` default · filled · unstyled	`'default'`	Field variant forwarded to the field frame.
`withDropdown`	`boolean \| undefined`	`false`	Open a time-controls dropdown on focus.
`withSeconds`	`boolean \| undefined`	`false`	Show the seconds segment.

Style slots

Every part of TimePicker can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`colon`	`styles={{ colon: { … } }}`
`description`	`styles={{ description: { … } }}`
`dropdown`	`styles={{ dropdown: { … } }}`
`error`	`styles={{ error: { … } }}`
`field`	`styles={{ field: { … } }}`
`label`	`styles={{ label: { … } }}`
`required`	`styles={{ required: { … } }}`
`segment`	`styles={{ segment: { … } }}`
`wrapper`	`styles={{ wrapper: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 493 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.