Skip to content

Time picker

Choose a time using the original radial clock face.

Installation

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

New here? Set up your project first. Styles, fonts, and required components are included. The command includes the components used by the examples below.

Usage

Values are Date objects. Use format="24hr" for a 24-hour clock or format="ampm" for a 12-hour clock.

Composition

Compose a local time window with minute steps and bounds. Keep the date and IANA time zone explicit in your application’s scheduling data.

Times are wall-clock values in the selected zone. Resolve them to instants with the booking date when saving.

Show composition code
tsx
'use client';
import { useState } from 'react';
import { TimePicker } from '@/components/ui/material/time-picker';
import { Dropdown } from '@/components/ui/material/dropdown';
import { Button } from '@/components/ui/material/button';

export default function SchedulingComposition() {
  const [start, setStart] = useState<Date | null>(null);
  const [end, setEnd] = useState<Date | null>(null);
  const [zone, setZone] = useState('Europe/Madrid');
  const [saved, setSaved] = useState('');
  return (
    <form
      className="max-w-sm"
      onSubmit={(event) => {
        event.preventDefault();
        if (start && end)
          setSaved(
            `${start.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}–${end.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })} in ${zone}`,
          );
      }}
    >
      <TimePicker
        label="Starts at"
        value={start}
        onChange={setStart}
        minuteStep={15}
        clearable
        onClear={() => setStart(null)}
        required
      />
      <TimePicker
        label="Ends at"
        value={end}
        onChange={setEnd}
        minTime={start ?? undefined}
        minuteStep={15}
        clearable
        onClear={() => setEnd(null)}
        required
      />
      <Dropdown
        label="Time zone"
        source={['Europe/Madrid', 'Europe/London', 'America/New_York']}
        value={zone}
        onChange={(value) => setZone(String(value))}
      />
      <p className="mb-4 text-toolbox-caption text-toolbox-text-secondary">
        Times are wall-clock values in the selected zone. Resolve them to instants with the booking date when saving.
      </p>
      <Button type="submit" primary raised>
        Save time window
      </Button>
      <p role="status" className="mt-4 text-toolbox-body">
        {saved}
      </p>
    </form>
  );
}

State and callbacks

  • Use value/onChange, or defaultValue for internal state and form reset. The dialog edits a draft time until confirmation.
  • Visibility is internal by default. Use defaultOpen to initialize it or open/onOpenChange to control it. When controlled, update open from onOpenChange; onDismiss reports dismissal.

API reference

Key props and defaults. Full types and inline documentation are included with the source in material/time-picker.

TimePicker

Property Type Default
clearable boolean

Show a clear action. Controlled consumers clear by setting value to null.

—
defaultOpen boolean —
defaultValue Date —
format TimeFormat '24hr'
labels Partial<TimePickerLabels> —
layout 'portrait' | 'landscape' | 'responsive'

Preserve portrait, force landscape, or adapt to wide landscape viewports.

—
maxTime Date —
minTime Date

Inclusive local clock bounds. A minimum later than the maximum permits an overnight interval.

—
minuteStep number

Allowed minute marks within each hour, from 1 through 60. Defaults to 1.

—
onChange (time: Date, event?: React.MouseEvent<HTMLElement>) => void —
onOpenChange (open: boolean) => void —
open boolean —
readOnly boolean

Keep the value focusable and submitted while preventing edits and validation.

—
value Date | null —

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