Time picker

Overview.

Time picker is a TextField-shaped trigger that opens a scrollable column of time slots. Click a slot, the field commits and closes. The geometry intentionally mirrors Date picker so the two read as a pair — the popover content swaps a calendar for a list, but the trigger, the focus ring, the disabled tone, and the error reframing are identical.

Sizes.

Two surfaces. The form-field input is the default; the filter chip is the dashboard / toolbar variant.

States.

Empty, filled, with helper, error, disabled. Same vocabulary as every other input in the system.

Step.

Pick the granularity that matches the operational reality. 30 minutes is the default; 15 for appointment slots; 60 when finer detail would imply false precision.

24h vs 12h.

24-hour is the default — it's the European convention and matches every other timestamp in the product. Pass format="12h" for AM/PM markets, or formatTime for a custom function (locale-specific separators, half-past spelling, etc.).

Bounded by min and max.

Out-of-bounds slots are pruned from the list, not rendered as greyed-out rows. A long ghost list above and below the valid window costs more attention than it gives back.

Range filters.

The system doesn't ship a dedicated TimeRangePicker. Two TimePickers compose the same idea with less surface area — bound the second picker by the first's value, and bump the end forward if the user picks a start past it.

Anatomy.

Three parts on the trigger row, plus the popover that opens beneath it. The popover is the same rounded-corner card the rest of the system uses for floating UI.

Behavior.

• 01Click commits. Picking a slot writes the value and closes the popover. There is no Apply button — time is a single intent.
• 02Open scrolls to the selected slot. The popover opens with the currently-selected (or nearest in-bounds) slot centred in the viewport. Arrow keys then walk forward or back from there — no rummaging.
• 03Type a digit, jump to that hour. Numeric type-ahead with a 600 ms buffer: type 9 to jump to the first 09:XX slot, or 1430 to jump to 14:30 specifically. Keystrokes that arrive after the buffer expires start a new search.
• 04Out-of-bounds slots are pruned, not disabled. min and max shorten the list rather than rendering a long greyed-out tail. A hard-bounded picker still shows the user only what they can choose.
• 05Mouse hover and keyboard arrow are the same state. Same rule as the rest of the system: there is no separate “mouse-focus” rectangle. Moving the cursor moves the highlight, ArrowDown does the same.

Accessibility.

The trigger is a button with aria-haspopup="dialog"; the popover is a non-modal role="dialog" with a single role="listbox" inside it. Keyboard focus moves into the listbox on open and returns to the trigger on commit or Esc.

• ↑ ↓Move highlight one slot.
• PgUp / PgDnJump roughly an hour at the current step.
• Home / EndFirst or last slot in the list.
• Enter / SpaceCommit the highlighted slot.
• EscClose without commit; focus returns to the trigger.
• 0 – 9Type-ahead: jump to the first slot whose hour starts with the typed digits.

Code.

Two patterns: a simple controlled time, and a between-X-and-Y range built from two pickers.

Controlled

import { TimePicker, type TimeOfDay } from "@flatpay-dk/ui";

function OpeningHour() {
  const [open, setOpen] = React.useState<TimeOfDay | null>({ hours: 9, minutes: 30 });
  return (
    <TimePicker
      label="Opening time"
      value={open}
      onValueChange={setOpen}
      step={30}
      helpText="Used to start the daily schedule."
    />
  );
}

Range filter

import { TimePicker, type TimeOfDay } from "@flatpay-dk/ui";

const minutes = (t: TimeOfDay) => t.hours * 60 + t.minutes;

function HoursRange() {
  const [from, setFrom] = React.useState<TimeOfDay | null>({ hours: 9, minutes: 0 });
  const [to,   setTo]   = React.useState<TimeOfDay | null>({ hours: 17, minutes: 0 });

  return (
    <div className="flex items-center gap-3">
      <TimePicker
        size="filter"
        value={from}
        onValueChange={(next) => {
          setFrom(next);
          // Bump the end forward if the new start is past it.
          if (next && to && minutes(next) > minutes(to)) setTo(next);
        }}
      />
      <span className="text-sm font-semibold text-foreground/55">to</span>
      <TimePicker
        size="filter"
        value={to}
        min={from ?? undefined}
        onValueChange={setTo}
      />
    </div>
  );
}

Best practices.

Props.

Related.