Timepicker

InstallationCopy Anchor Link

npx vayu-ui-cli@latest add time-picker

UsageCopy Anchor Link

AnatomyCopy Anchor Link

import { Timepicker } from 'vayu-ui';

<Timepicker.Root value={time} onValueChange={setTime} format="12h" label="Start time">
  <Timepicker.Trigger />
  <Timepicker.Content>
    <Timepicker.TimeGrid />
    <Timepicker.Footer />
  </Timepicker.Content>
</Timepicker.Root>;

{
  /* Custom column layout */
}
<Timepicker.Root format="24h">
  <Timepicker.Trigger />
  <Timepicker.Content>
    <Timepicker.HourColumn />
    <Timepicker.MinuteColumn />
    <Timepicker.Error />
    <Timepicker.Footer />
  </Timepicker.Content>
</Timepicker.Root>;

• Timepicker.Root — Root container. Manages time state, format, mode, and provides context to children.
• Timepicker.Trigger — Button with inline editing. Displays the selected time and opens the dropdown.
• Timepicker.Content — Portal-based dropdown with focus trap and auto-positioning.
• Timepicker.TimeGrid — Pre-configured layout of hour, minute, and period columns.
• Timepicker.HourColumn — Individual hour selection column with scroll and keyboard navigation.
• Timepicker.MinuteColumn — Individual minute selection column, respects minuteStep.
• Timepicker.PeriodColumn — AM/PM toggle column, only rendered in 12h format.
• Timepicker.Footer — Action buttons for clearing and applying selection.
• Timepicker.Error — Error message display within the dropdown.

AccessibilityCopy Anchor Link

• Keyboard Support:
  • Enter / Space — Select the focused time item or open the dropdown.
  • ArrowDown / ArrowUp — Navigate within a time column (wraps circularly).
  • ArrowLeft / ArrowRight — Navigate between columns (hour, minute, period).
  • Home / End — Jump to first / last item in the current column.
  • Escape — Close the dropdown and return focus to the trigger.
  • Tab — Move focus through the dropdown content (trapped while open). Shift+Tab reverses.
  • Backspace — In trigger inline mode, decrement the focused field value.
• ARIA Attributes:
  • role="combobox" and aria-expanded on Timepicker.Trigger.
  • role="dialog" and aria-modal="true" on Timepicker.Content.
  • role="listbox" on each time column with aria-label ("Hour", "Minute", "Period").
  • role="option" with aria-selected and aria-disabled on each time item.
  • aria-labelledby links the label to the trigger for identification.
• Focus Behavior:
  • Opening the dropdown focuses the first selected option, or the first enabled item.
  • Closing via Escape returns focus to the trigger.
  • Focus is trapped within the dropdown while open.
  • Selected items auto-scroll into view when the dropdown opens.

Screen reader behaviorCopy Anchor Link

When a user focuses the trigger, the screen reader announces the label, the currently selected time or placeholder, and the expanded state via aria-expanded. When the dropdown opens, the dialog role is announced along with the column listboxes. Each time option is announced with its value, selected state via aria-selected, and disabled state via aria-disabled. Navigating between columns with arrow keys announces the column label. In range mode, the current phase (start or end) is announced when switching. Closing the dropdown returns focus to the trigger, which announces the updated time value.

Component Folder StructureCopy Anchor Link

TimePicker/
├── TimePicker.tsx           # Root component with context provider and state management
├── TimePickerTrigger.tsx    # Trigger with inline editing and keyboard navigation
├── TimePickerContent.tsx    # Portal-based dropdown with focus trap and positioning
├── TimePickerColumns.tsx    # Hour, Minute, Period columns with grid layout
├── TimePickerFooter.tsx     # Footer actions (Clear, Apply) and error display
├── utils.ts                 # Time parsing, formatting, validation utilities
├── types.ts                 # TypeScript type definitions
├── index.ts                 # Re-exports all components and types
└── README.md                # Component usage reference

PropsCopy Anchor Link

Timepicker.RootCopy Anchor Link

Timepicker.TriggerCopy Anchor Link

Timepicker.ContentCopy Anchor Link

Timepicker.TimeGridCopy Anchor Link

Timepicker.HourColumnCopy Anchor Link

Timepicker.MinuteColumnCopy Anchor Link

Timepicker.PeriodColumnCopy Anchor Link

Timepicker.FooterCopy Anchor Link

Timepicker.ErrorCopy Anchor Link