TimePicker

TimePicker uses @internationalized/date for time manipulation (Time, locale-aware formatting). The wheel exchanges a Time value internally, while the selected option stores an ISO time string. For full context on the time type exposed through formatTime, read the @internationalized/date docs alongside this page.

Import

import { TimePicker } from 'heroui-native-pro';

Anatomy

<TimePicker>
  <Label>...</Label>
  <TimePicker.Select>
    <TimePicker.Trigger>
      <TimePicker.Value />
      <TimePicker.TriggerIndicator />
    </TimePicker.Trigger>
    <TimePicker.Portal>
      <TimePicker.Overlay />
      <TimePicker.Content>
        <TimePicker.Wheel>
          <TimePicker.WheelHour />
          <TimePicker.WheelMinute />
          <TimePicker.WheelPeriod />
          <TimePicker.WheelIndicator />
          <TimePicker.WheelMask />
        </TimePicker.Wheel>
      </TimePicker.Content>
    </TimePicker.Portal>
  </TimePicker.Select>
  <Description>...</Description>
</TimePicker>

• TimePicker: Root container that manages time selection state, open state, label formatting, and form field context (for Label, Description, FieldError). Supports controlled and uncontrolled modes.
• TimePicker.Select: Pre-wired Select root connected to the TimePicker context. State props (value, isOpen, onValueChange, onOpenChange) are managed by the root. Always single selection mode.
• TimePicker.Trigger: Pressable trigger button that opens the wheel overlay. Inherits invalid border styling from the root.
• TimePicker.Value: Text display for the selected time label. Shows a placeholder when no time is selected.
• TimePicker.TriggerIndicator: Indicator icon inside the trigger. Defaults to a clock icon instead of a chevron.
• TimePicker.Portal: Portal wrapper that re-provides TimePicker context across the portal boundary.
• TimePicker.Overlay: Backdrop overlay behind the wheel content.
• TimePicker.Content: Content container for the wheel popup. Supports "popover", "dialog", and "bottom-sheet" presentations. Dialog swipe-to-dismiss is always disabled, and the bottom sheet defaults to no pan-down-to-close.
• TimePicker.Wheel: Pre-wired wheel time selector that commits the selected time live on scroll and updates the trigger label while the surface stays open. Renders the default wheel parts when no children are passed.
• TimePicker.WheelHour: Hour column.
• TimePicker.WheelMinute: Minute column.
• TimePicker.WheelPeriod: AM/PM column. Rendered by default only in 12-hour mode.
• TimePicker.WheelIndicator: Shared selection band spanning every column.
• TimePicker.WheelMask: Top / bottom fade overlays. Defaults its gradient color to the overlay surface so it blends with the popup background.

Usage

Basic Usage

The TimePicker uses a popover presentation by default. Pass TimePicker.Wheel with no children to render the default hour, minute, period, indicator, and mask parts.

<TimePicker>
  <Label>Reminder</Label>
  <TimePicker.Select>
    <TimePicker.Trigger>
      <TimePicker.Value />
      <TimePicker.TriggerIndicator />
    </TimePicker.Trigger>
    <TimePicker.Portal>
      <TimePicker.Overlay />
      <TimePicker.Content presentation="popover" width="trigger">
        <TimePicker.Wheel />
      </TimePicker.Content>
    </TimePicker.Portal>
  </TimePicker.Select>
</TimePicker>

Dialog Presentation

Display the wheel in a centered modal dialog.

<TimePicker>
  <Label>Reminder</Label>
  <TimePicker.Select presentation="dialog">
    <TimePicker.Trigger>
      <TimePicker.Value />
      <TimePicker.TriggerIndicator />
    </TimePicker.Trigger>
    <TimePicker.Portal>
      <TimePicker.Overlay />
      <TimePicker.Content presentation="dialog">
        <TimePicker.Wheel />
      </TimePicker.Content>
    </TimePicker.Portal>
  </TimePicker.Select>
</TimePicker>

Bottom Sheet Presentation

Display the wheel in a bottom sheet.

<TimePicker>
  <Label>Reminder</Label>
  <TimePicker.Select presentation="bottom-sheet">
    <TimePicker.Trigger>
      <TimePicker.Value />
      <TimePicker.TriggerIndicator />
    </TimePicker.Trigger>
    <TimePicker.Portal>
      <TimePicker.Overlay />
      <TimePicker.Content presentation="bottom-sheet">
        <TimePicker.Wheel />
      </TimePicker.Content>
    </TimePicker.Portal>
  </TimePicker.Select>
</TimePicker>

Hour Format and Minute Interval

Use hourFormat to switch between 12-hour and 24-hour mode, and minuteInterval to control the step between minute options. In 24-hour mode the AM/PM column is omitted.

<TimePicker hourFormat={24} minuteInterval={5} locale="en-GB">
  <Label>Departure</Label>
  <TimePicker.Select>
    <TimePicker.Trigger>
      <TimePicker.Value placeholder="Select a time" />
      <TimePicker.TriggerIndicator />
    </TimePicker.Trigger>
    <TimePicker.Portal>
      <TimePicker.Overlay />
      <TimePicker.Content presentation="popover" width="trigger">
        <TimePicker.Wheel />
      </TimePicker.Content>
    </TimePicker.Portal>
  </TimePicker.Select>
</TimePicker>

Custom Format Function

Override the trigger label entirely with formatTime.

function formatCompactTime(time: Time): string {
  const hour12 = time.hour % 12 === 0 ? 12 : time.hour % 12;
  const minute = String(time.minute).padStart(2, '0');
  const marker = time.hour < 12 ? 'a.m.' : 'p.m.';
  return `${hour12}:${minute} ${marker}`;
}

<TimePicker formatTime={formatCompactTime}>
  <Label>Custom format</Label>
  <TimePicker.Select>
    <TimePicker.Trigger>
      <TimePicker.Value />
      <TimePicker.TriggerIndicator />
    </TimePicker.Trigger>
    <TimePicker.Portal>
      <TimePicker.Overlay />
      <TimePicker.Content presentation="popover" width="trigger">
        <TimePicker.Wheel />
      </TimePicker.Content>
    </TimePicker.Portal>
  </TimePicker.Select>
</TimePicker>;

Field States

Use root props for required, invalid, and disabled states. Combine isInvalid with FieldError to display validation messages; the trigger shows a danger border.

<TimePicker isInvalid>
  <Label>Cutoff</Label>
  <TimePicker.Select>
    <TimePicker.Trigger>
      <TimePicker.Value />
      <TimePicker.TriggerIndicator />
    </TimePicker.Trigger>
    <TimePicker.Portal>
      <TimePicker.Overlay />
      <TimePicker.Content presentation="popover" width="trigger">
        <TimePicker.Wheel />
      </TimePicker.Content>
    </TimePicker.Portal>
  </TimePicker.Select>
  <Description hideOnInvalid>Must be during business hours.</Description>
  <FieldError>Please select a valid cutoff time.</FieldError>
</TimePicker>

Example

import type { Time } from '@internationalized/date';
import { Description, FieldError, Label } from 'heroui-native';
import { TimePicker } from 'heroui-native-pro';
import { View } from 'react-native';

function formatCompactTime(time: Time): string {
  const hour12 = time.hour % 12 === 0 ? 12 : time.hour % 12;
  const minute = String(time.minute).padStart(2, '0');
  const marker = time.hour < 12 ? 'a.m.' : 'p.m.';
  return `${hour12}:${minute} ${marker}`;
}

export default function TimePickerExample() {
  return (
    <View className="flex-1 justify-center px-5 gap-12">
      <TimePicker formatTime={formatCompactTime}>
        <Label>Reminder</Label>
        <TimePicker.Select>
          <TimePicker.Trigger>
            <TimePicker.Value placeholder="Pick a reminder time" />
            <TimePicker.TriggerIndicator />
          </TimePicker.Trigger>
          <TimePicker.Portal>
            <TimePicker.Overlay />
            <TimePicker.Content
              presentation="popover"
              width="trigger"
              className="items-center justify-center"
            >
              <TimePicker.Wheel />
            </TimePicker.Content>
          </TimePicker.Portal>
        </TimePicker.Select>
        <Description>Required to schedule the notification.</Description>
      </TimePicker>

      <TimePicker isInvalid hourFormat={24} minuteInterval={5}>
        <Label>Cutoff</Label>
        <TimePicker.Select>
          <TimePicker.Trigger>
            <TimePicker.Value />
            <TimePicker.TriggerIndicator />
          </TimePicker.Trigger>
          <TimePicker.Portal>
            <TimePicker.Overlay />
            <TimePicker.Content
              presentation="popover"
              width="trigger"
              className="items-center justify-center"
            >
              <TimePicker.Wheel />
            </TimePicker.Content>
          </TimePicker.Portal>
        </TimePicker.Select>
        <Description hideOnInvalid>Must be during business hours.</Description>
        <FieldError>Please select a valid cutoff time.</FieldError>
      </TimePicker>
    </View>
  );
}

API Reference

TimePicker

TimePickerOption

TimePickerTimeDisplayFormat

Built-in time label presets:

• 'short' — hour and minute only (e.g. "2:30 PM" / "14:30") (default)
• 'medium' — includes seconds (e.g. "2:30:00 PM")

WheelTimePickerHourFormat

Hour display mode for the wheel and label formatting:

• 12 — twelve-hour clock with an AM/PM period column (default)
• 24 — twenty-four-hour clock without a period column

AnimationRootDisableAll

Animation configuration for the TimePicker root. Can be:

• "disable-all": Disable all animations including children (cascades down)
• undefined: Use default animations

TimePicker.Select

TimePicker.Trigger

TimePicker.Value

TimePicker.TriggerIndicator

SelectTriggerIndicatorIconProps

TimePicker.Portal

TimePicker.Overlay

TimePicker.Content

The content component is a union type based on the presentation prop. The dialog isSwipeable prop is removed — TimePicker always disables dialog swipe-to-dismiss, and the bottom sheet defaults to no pan-down-to-close.

Popover presentation

Dialog presentation

Bottom sheet presentation

TimePicker.Wheel

Wired from TimePicker context; value, defaultValue, and onValueChange are managed by the root. Each scroll commits the selected option (formatted label + select value) live while the surface stays open. When children are omitted, the default wheel parts are rendered (period column only in 12-hour mode).

TimePicker.WheelHour

Hour column. The underlying name and items are owned by the wheel so the stored value stays correct.

TimePicker.WheelMinute

Minute column. Same props as TimePicker.WheelHour; the underlying name and items are owned by the wheel.

TimePicker.WheelPeriod

AM/PM column. Same props as TimePicker.WheelHour; the underlying name and items are owned by the wheel. Rendered by default only in 12-hour mode.

TimePicker.WheelIndicator

Shared selection band spanning every column.

ElementSlots<WheelPickerGroupIndicatorSlots>

TimePicker.WheelMask

Top / bottom fade overlays. When color is omitted it defaults to the Select overlay surface color so the gradient blends with the popup background.

ElementSlots<WheelPickerGroupMaskSlots>

Hooks

useTimePicker

Hook to access the TimePicker context. Must be used within a TimePicker component.

import { useTimePicker } from 'heroui-native-pro';

const { value, commitTime, isOpen, formatLabel } = useTimePicker();

Returns: TimePickerContextValue

TimePickerCommitOptions