TimePicker

Time field with segmented hour/minute editing and an optional wheel popover; built on React Aria TimeField.

stable
since v0.1.0
2.14 kB
forms

Rendered as a segmented control — a clock icon, the hour/minute segments, and the chevron sit as raised tiles inside a tinted track (the same container the other inputs use); variant tints the track.

Preview

Open

tsx

import { TimePicker } from '@arshad-shah/cynosure-react';
import { Time } from '@internationalized/date';

export default function Example() {
  return (
    <div style={{ width: '240px' }}>
      <TimePicker aria-label="Meeting time" defaultValue={new Time(9, 30)} />
    </div>
  );
}

Usage

import { TimePicker } from "@arshad-shah/cynosure-react";
import { Time } from "@internationalized/date";

<TimePicker aria-label="Meeting time" defaultValue={new Time(9, 30)} />

TimePicker accepts a Time value from @internationalized/date. The trigger opens a popover with a wheel picker for hours and minutes.

Hour cycle

Use hourCycle to switch between 12-hour (12) and 24-hour (24) display.

Preview

Open

tsx

import { TimePicker } from '@arshad-shah/cynosure-react';
import { Time } from '@internationalized/date';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', width: '240px' }}>
      <TimePicker aria-label="12-hour" hourCycle={12} defaultValue={new Time(14, 30)} />
      <TimePicker aria-label="24-hour" hourCycle={24} defaultValue={new Time(14, 30)} />
    </div>
  );
}

Minute step

Set minuteStep to constrain the wheel’s minute column (e.g. 5-minute or 15-minute intervals).

Preview

Open

tsx

import { TimePicker } from '@arshad-shah/cynosure-react';
import { Time } from '@internationalized/date';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', width: '240px' }}>
      <TimePicker aria-label="Every 5 minutes" minuteStep={5} defaultValue={new Time(10, 0)} />
      <TimePicker aria-label="Every 15 minutes" minuteStep={15} defaultValue={new Time(10, 0)} />
    </div>
  );
}

Controlled

Drive the value from parent state with value and onChange.

Preview

Open

tsx

import { TimePicker } from '@arshad-shah/cynosure-react';
import { Time } from '@internationalized/date';
import { useState } from 'react';

export default function Example() {
  const [value, setValue] = useState<Time | null>(new Time(8, 0));
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', width: '240px' }}>
      <TimePicker
        aria-label="Start time"
        value={value}
        onChange={(t) => setValue(t as Time | null)}
      />
      <span style={{ fontSize: '0.875rem', color: 'var(--c-fg-muted)' }}>
        Selected: {value ? value.toString() : '(none)'}
      </span>
    </div>
  );
}

States

Preview

Open

tsx

import { TimePicker } from '@arshad-shah/cynosure-react';
import { Time } from '@internationalized/date';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', width: '240px' }}>
      <TimePicker aria-label="Default" defaultValue={new Time(9, 0)} />
      <TimePicker aria-label="Invalid" defaultValue={new Time(9, 0)} invalid />
      <TimePicker aria-label="Read-only" defaultValue={new Time(9, 0)} isReadOnly />
      <TimePicker aria-label="Disabled" defaultValue={new Time(9, 0)} isDisabled />
    </div>
  );
}

API

PropTypeDefaultDescription

label

ReactNode

—

Visible label, also used as the picker's accessible name when a string.

size

"sm"|"md"|"lg"

—

Accepted for API parity with other form controls.

variant

"outline"|"filled"|"ghost"

"outline"

Visual treatment.

invalid

boolean

—

Renders the invalid state.

className

string

—

style

CSSProperties

—

minuteStep

number

Step in minutes for the wheel's minute column.

value

TimeValue|null

—

defaultValue

TimeValue|null

—

onChange

((value: TimeValue | null) => void)

—

Accessibility

Hour and minute segments are individual spinbuttons with aria-valuemin/aria-valuemax/aria-valuenow.
Arrow Up/Down change the focused segment; Arrow Left/Right move between segments.
The trigger button carries aria-label="Open time picker" and opens a Dialog with the wheel.
Provide an aria-label (or pass a label) so the whole field is announced as a time picker.

Recipes

Pair with DatePicker for full date-and-time entry.
Use hourCycle={24} for backend-facing forms; hourCycle={12} for end-user scheduling.
Set minuteStep={15} for booking flows to keep slots aligned to common intervals.