Time Picker

A time field people type into, with a list of times to pick from.

import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerBasic() {
  return (
    <TimePicker>
      <TimePickerInput aria-label="Start time" />
      <TimePickerContent />
    </TimePicker>
  );
}

Installation

Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
Add time-picker
pnpm dlx shadcn@latest add @jarvis/time-picker

Usage

import * as React from "react";

import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export function StartTimePicker() {
  const [time, setTime] = React.useState<string | null>(null);

  return (
    <TimePicker value={time} onValueChange={setTime}>
      <TimePickerInput aria-label="Start time" />
      <TimePickerContent />
    </TimePicker>
  );
}

TimePickerInput splits the time into an hour, a minute and, on a 12-hour clock, AM or PM. Each part takes typed digits and moves on once it's filled, so 9, 3, 0, p gives 9:30 PM, and a or p sets AM or PM from any part. Arrow keys step a part up and down, and Backspace clears it. Pasting a time such as 14:30 or 2:30 pm fills every part, and pasting a number such as 45 fills only the focused one. TimePickerContent adds a clock button to the input that opens a list of times, every 15 minutes by default.

The value is a 24-hour HH:mm string, such as "21:30", the format of a native time input. onValueChange gets it once every part is filled in, and null once one is cleared.

Composition

TimePicker
- TimePickerInput
- TimePickerContent

Examples

With a label

Put the picker in a Field with a FieldLabel. The input reads out the field's FieldDescription and FieldError, and turns invalid or disabled with the field. Without a visible label, give the input an aria-label.

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerWithLabel() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor="reminder-time">Daily reminder</FieldLabel>
      <TimePicker defaultValue="08:30">
        <TimePickerInput id="reminder-time" className="w-full" />
        <TimePickerContent />
      </TimePicker>
      <FieldDescription>We'll nudge you at this time every weekday.</FieldDescription>
    </Field>
  );
}

With a date picker

Set a Date Picker beside it for a date and a time. They're the same height in each size.

import { DatePicker, DatePickerContent, DatePickerTrigger } from "@/components/ui/date-picker";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerDateAndTime() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor="meeting-date">Meeting starts</FieldLabel>
      <div className="flex gap-2">
        <DatePicker defaultValue={new Date(2025, 5, 12)}>
          <DatePickerTrigger id="meeting-date" className="min-w-0 flex-1" />
          <DatePickerContent />
        </DatePicker>
        <TimePicker defaultValue="14:00">
          <TimePickerInput aria-label="Start time" />
          <TimePickerContent />
        </TimePicker>
      </div>
      <FieldDescription>Guests see it in their own time zone.</FieldDescription>
    </Field>
  );
}

To combine their values, set the time on a copy of the date:

function combine(date: Date, time: string) {
  const [hours, minutes] = time.split(":").map(Number);
  const dateTime = new Date(date);
  dateTime.setHours(hours, minutes, 0, 0);
  return dateTime;
}

Hour cycle

The input follows the hour cycle of its locale, a DayPicker locale like the Date Picker's, which is 12 hours for the default English. hourCycle={24} runs hours from 0 to 23 instead, with no AM or PM. The list writes times the locale's way, and the input puts AM or PM first in locales that do, such as Chinese.

import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerHourCycle() {
  return (
    <TimePicker hourCycle={24} defaultValue="18:45">
      <TimePickerInput aria-label="Departure time" />
      <TimePickerContent />
    </TimePicker>
  );
}

Earliest and latest times

min and max bound the list, and the input turns invalid outside them. step sets the minutes between the times in the list. A min later than max makes a range that runs past midnight, so min="22:00" max="02:00" offers the times from 10:00 PM to 2:00 AM.

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerRange() {
  return (
    <Field className="w-48">
      <FieldLabel htmlFor="pickup-time">Pickup time</FieldLabel>
      <TimePicker min="09:00" max="17:00" step={30}>
        <TimePickerInput id="pickup-time" className="w-full" />
        <TimePickerContent />
      </TimePicker>
      <FieldDescription>Open 9:00 AM to 5:00 PM.</FieldDescription>
    </Field>
  );
}

Seconds

granularity="second" adds seconds, and the value becomes HH:mm:ss. Leave out TimePickerContent for an input on its own.

import { Field, FieldLabel } from "@/components/ui/field";
import { TimePicker, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerSeconds() {
  return (
    <Field className="w-48">
      <FieldLabel htmlFor="clip-start">Clip starts at</FieldLabel>
      <TimePicker granularity="second" hourCycle={24} defaultValue="00:01:30">
        <TimePickerInput id="clip-start" />
      </TimePicker>
    </Field>
  );
}

In a form

Give a Field or the picker a name, and the value submits under it as HH:mm, or pass form with a form's id when the picker sits outside it. With required, the form won't submit without a time, which fails as valueMissing. A time outside min and max, or one only partly typed, stops it too, as customError, so a FieldError matching it shows the reason. A form reset brings back defaultValue.

import { Button } from "@/components/ui/button";
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Form } from "@/components/ui/form";
import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";
import { toast } from "@/components/ui/toast";

export default function TimePickerForm() {
  return (
    <Form
      className="max-w-sm"
      onFormSubmit={(values) =>
        toast.add({ title: "Pickup booked", description: `See you at ${values.pickup}.` })
      }
    >
      <Field name="pickup">
        <FieldLabel>Pickup time</FieldLabel>
        <TimePicker required min="09:00" max="17:00" step={30}>
          <TimePickerInput className="w-full" />
          <TimePickerContent />
        </TimePicker>
        <FieldDescription>Open 9:00 AM to 5:00 PM.</FieldDescription>
        <FieldError match="valueMissing">Choose a pickup time.</FieldError>
        <FieldError match="customError" />
      </Field>
      <Button type="submit" variant="primary" className="self-start">
        Book pickup
      </Button>
    </Form>
  );
}

Sizes

size on the input matches the sizes of buttons, inputs and selects.

import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

const sizes = ["sm", "default", "lg"] as const;

export default function TimePickerSizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {sizes.map((size) => (
        <TimePicker key={size} defaultValue="09:30">
          <TimePickerInput size={size} aria-label={`Time, ${size}`} />
          <TimePickerContent />
        </TimePicker>
      ))}
    </div>
  );
}

Invalid

Set invalid on the Field, and explain the problem with a FieldError.

import { Field, FieldError, FieldLabel } from "@/components/ui/field";
import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerInvalid() {
  return (
    <Field invalid className="w-48">
      <FieldLabel htmlFor="end-time">End time</FieldLabel>
      <TimePicker defaultValue="08:00">
        <TimePickerInput id="end-time" className="w-full" />
        <TimePickerContent />
      </TimePicker>
      <FieldError>End the event after it starts, at 9:00 AM.</FieldError>
    </Field>
  );
}

Disabled

import { TimePicker, TimePickerContent, TimePickerInput } from "@/components/ui/time-picker";

export default function TimePickerDisabled() {
  return (
    <TimePicker disabled defaultValue="12:00">
      <TimePickerInput aria-label="Lunch time" />
      <TimePickerContent />
    </TimePicker>
  );
}

Props

TimePicker takes the props of Popover's root too, such as open and onOpenChange for the list.

Part	Extends
TimePicker	Base UI's Popover.Root
TimePickerInput	<div>
TimePickerContent	PopoverContent

The tables leave out className, style and render. Parts built on Base UI take them as its styling and composition guides describe.

TimePicker

Prop	Type	Default
`defaultOpen` Whether the popover is initially open. To render a controlled popover, use the `open` prop instead.	`boolean`	`false`
`open` Whether the popover is currently open.	`boolean`	—
`onOpenChange` Event handler called when the popover is opened or closed.	`((open: boolean, eventDetails: Popover.Root.ChangeEventDetails) => void)`	—
`onOpenChangeComplete` Event handler called after any animations complete when the popover is opened or closed.	`((open: boolean) => void)`	—
`actionsRef` A ref to imperative actions. `unmount`: Ends the closing phase of the popover after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the popover completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. `close`: Closes the popover imperatively when called.	`React.RefObject<PopoverRootActions \| null>`	—
`modal` Determines if the popover enters a modal state when open. `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled. `false`: user interaction with the rest of the document is allowed. `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as Tailwind's `sr-only` utility. When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch screen readers can escape the popup.	`"trap-focus" \| boolean`	`false`
`triggerId` ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).	`string \| null`	—
`defaultTriggerId` ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.	`string \| null`	—
`handle` A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state.	`Popover.Handle<unknown>`	—
`children` The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger.	`PayloadChildRenderFunction<unknown> \| React.ReactNode`	—
`value` The time as 24-hour `HH:mm`, or `HH:mm:ss` with `granularity="second"`. `null` when there's none.	`string \| null`	—
`defaultValue`	`string \| null`	`null`
`onValueChange` Called once every part of the time is filled in, and with `null` once one is cleared.	`((value: string \| null) => void)`	—
`hourCycle` Whether hours run from 1 to 12 with AM and PM, or from 0 to 23.	`12 \| 24`	`The locale's`
`granularity` The smallest part of the time people set.	`"minute" \| "second"`	`"minute"`
`step` Minutes between the times the list offers.	`number`	`15`
`min` The earliest time, as `HH:mm`. The list starts here, and earlier times are invalid. A `min` after `max` makes a range that runs past midnight.	`string`	—
`max` The latest time, as `HH:mm`. The list ends here, and later times are invalid.	`string`	—
`locale` A DayPicker locale, for the hour cycle, the AM and PM labels and the times in the list.	`Partial<DayPickerLocale>`	—
`name` Submits the value with a form under this name.	`string`	—
`form` The `id` of the form to submit the value with, when the picker isn't inside it.	`string`	—
`required` Whether a form can't be submitted without a time. A time outside `min` and `max` stops it too.	`boolean`	`false`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`

TimePickerInput

Prop	Type	Default
`size`	`"default" \| "lg" \| "sm"`	`"default"`
`triggerLabel` The clock button's accessible name, when there's a `TimePickerContent` for it to open.	`string`	`"Choose time"`

TimePickerContent

Prop	Type	Default
`side` Which side of the anchor element to align the popup against. May automatically change to avoid collisions.	`"bottom" \| "inline-end" \| "inline-start" \| "left" \| "right" \| "top"`	`"bottom"`
`sideOffset` Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. `data.side`: which side of the anchor element the positioner is aligned against. `data.align`: how the positioner is aligned relative to the specified side.	`number \| OffsetFunction`	`4`
`align` How to align the popup relative to the specified side.	`"center" \| "end" \| "start"`	`"start"`
`alignOffset` Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. `data.side`: which side of the anchor element the positioner is aligned against. `data.align`: how the positioner is aligned relative to the specified side.	`number \| OffsetFunction`	`0`
`aria-label` The list's accessible name.	`string`	`"Times"`