DateTimePicker

Import

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

Anatomy

<DateTimePicker>
  <DateTimePicker.Select>
    <DateTimePicker.Trigger>
      <DateTimePicker.Value />
      <DateTimePicker.TriggerIndicator />
    </DateTimePicker.Trigger>
    <DateTimePicker.Portal>
      <DateTimePicker.Overlay />
      <DateTimePicker.Content presentation="popover">
        <DateTimePicker.Wheel />
      </DateTimePicker.Content>
    </DateTimePicker.Portal>
  </DateTimePicker.Select>
</DateTimePicker>

DateTimePicker: Field shell owning selection, open state, and commit behavior. Forwards minValue / maxValue / hourFormat / minuteInterval / locale / formatDate to DateTimePicker.Wheel.
DateTimePicker.Select: Wires Select (single mode) to the root state.
DateTimePicker.Portal: Portals content and re-provides DateTimePicker context.
DateTimePicker.Overlay: Backdrop behind portaled content.
DateTimePicker.Content: Presentation surface (popover / dialog / bottom-sheet).
DateTimePicker.Trigger: Trigger surface with invalid border styling.
DateTimePicker.Value: Selected label / placeholder.
DateTimePicker.TriggerIndicator: Trailing calendar icon (default).
DateTimePicker.Wheel: Wheel date-time selector wired to commit on scroll; renders the default wheel parts (WheelDate, WheelHour, WheelMinute, WheelPeriod in 12-hour mode, WheelIndicator, WheelMask) when no children are passed.

Usage

Basic usage (managed state)

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

Bounded date range

Limit the selectable days with minValue / maxValue, forwarded to the wheel.

import { today, getLocalTimeZone } from '@internationalized/date';

const start = today(getLocalTimeZone());

<DateTimePicker minValue={start} maxValue={start.add({ months: 6 })}>
  <DateTimePicker.Select>
    <DateTimePicker.Trigger>
      <DateTimePicker.Value />
      <DateTimePicker.TriggerIndicator />
    </DateTimePicker.Trigger>
    <DateTimePicker.Portal>
      <DateTimePicker.Overlay />
      <DateTimePicker.Content presentation="popover" width="trigger">
        <DateTimePicker.Wheel />
      </DateTimePicker.Content>
    </DateTimePicker.Portal>
  </DateTimePicker.Select>
</DateTimePicker>;

24-hour mode with interval

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

Custom label

Override the committed trigger label with formatDateTime.

<DateTimePicker
  formatDateTime={(value) =>
    `${value.month}/${value.day} ${value.hour}:${String(value.minute).padStart(2, '0')}`
  }
>
  <DateTimePicker.Select>
    <DateTimePicker.Trigger>
      <DateTimePicker.Value />
      <DateTimePicker.TriggerIndicator />
    </DateTimePicker.Trigger>
    <DateTimePicker.Portal>
      <DateTimePicker.Overlay />
      <DateTimePicker.Content presentation="popover" width="trigger">
        <DateTimePicker.Wheel />
      </DateTimePicker.Content>
    </DateTimePicker.Portal>
  </DateTimePicker.Select>
</DateTimePicker>

Field states

isRequired, isInvalid, and isDisabled integrate with Label, Description, and FieldError.

<DateTimePicker isInvalid>
  <Label>Cutoff</Label>
  <DateTimePicker.Select>
    <DateTimePicker.Trigger>
      <DateTimePicker.Value />
      <DateTimePicker.TriggerIndicator />
    </DateTimePicker.Trigger>
    <DateTimePicker.Portal>
      <DateTimePicker.Overlay />
      <DateTimePicker.Content presentation="popover" width="trigger">
        <DateTimePicker.Wheel />
      </DateTimePicker.Content>
    </DateTimePicker.Portal>
  </DateTimePicker.Select>
  <FieldError>Please select a valid date and time.</FieldError>
</DateTimePicker>

API Reference

prop	type	default	description
`children`	`React.ReactNode`	-	Compound children
`isDisabled`	`boolean`	`false`	Whether the entire field is disabled
`isInvalid`	`boolean`	`false`	Whether the field is in an invalid state
`isRequired`	`boolean`	`false`	Whether the field is required
`className`	`string`	-	Additional CSS classes
`animation`	`AnimationRootDisableAll`	-	Animation configuration. Cascades `disable-all` to all children
`value`	`DateTimePickerOption`	-	Controlled selected option (single mode)
`defaultValue`	`DateTimePickerOption`	-	Uncontrolled initial selected option
`onValueChange`	`(value: DateTimePickerOption \| undefined) => void`	-	Called when the selected option changes
`isOpen`	`boolean`	-	Controlled open state of the select surface
`isDefaultOpen`	`boolean`	-	Uncontrolled initial open state
`onOpenChange`	`(open: boolean) => void`	-	Called when the open state changes
`minValue`	`CalendarDate`	`today`	Inclusive lower bound of the date column, forwarded to the wheel
`maxValue`	`CalendarDate`	`today + 1y`	Inclusive upper bound of the date column, forwarded to the wheel
`hourFormat`	`WheelDateTimePickerHourFormat`	`12`	Hour display mode, used for the wheel and label formatting
`minuteInterval`	`number`	`1`	Step between consecutive minute options, forwarded to the wheel
`dateTimeDisplayFormat`	`DateTimePickerDisplayFormat`	`short`	Preset used to build the trigger label. Ignored when `formatDateTime` is set
`locale`	`string`	`en-US`	BCP 47 locale for label formatting and the wheel's localized date / AM/PM labels
`formatDate`	`WheelDateTimePickerFormatDate`	-	Overrides the wheel's date column label formatting
`formatDateTime`	`(value: CalendarDateTime) => string`	-	Overrides `dateTimeDisplayFormat`, `hourFormat`, and `locale` for the committed label
`...ViewProps`	`ViewProps`	-	All standard React Native View props are supported

DateTimePickerDisplayFormat

Built-in date-time label styles.

"short": month / day / year + hour and minute (e.g. "Jun 1, 2026, 2:30 PM").
"medium": includes the weekday and seconds (e.g. "Mon, Jun 1, 2026, 2:30:00 PM").

DateTimePickerOption

Single date-time option (same shape as single-mode Select value).

prop	type	description
`value`	`string`	ISO date-time string (e.g. `"2026-06-01T14:30:00"`)
`label`	`string`	Display text

Wires Select (single mode) to the root state. Same props as Select minus the state props (value / defaultValue / onValueChange / isOpen / isDefaultOpen / onOpenChange / selectionMode).

DateTimePicker.Portal

Portals content and re-provides DateTimePicker context. Same props as Select.Portal.

DateTimePicker.Overlay

Backdrop behind portaled content. Same props as Select.Overlay.

DateTimePicker.Content

Presentation surface. Same props as Select.Content, minus the dialog isSwipeable prop (DateTimePicker always disables dialog swipe-to-dismiss).

DateTimePicker.Trigger

Trigger surface with invalid border styling. Extends Select.Trigger (minus variant).

prop	type	default	description
`isInvalid`	`boolean`	-	When `true`, applies a 1.5px danger border. When omitted, uses `FormField` context

DateTimePicker.Value

Selected label / placeholder. Extends Select.Value.

prop	type	default	description
`placeholder`	`string`	`"Choose a date & time"`	Shown when no date-time is selected

DateTimePicker.TriggerIndicator

Trailing calendar icon (default). Same props as Select.TriggerIndicator.

DateTimePicker.Wheel

Wheel date-time selector wired to commit on scroll. Same props as WheelDateTimePicker minus the value props (value / defaultValue / onValueChange), which are wired from DateTimePicker context. Each scroll updates the selected option live while the surface stays open.

DateTimePicker.WheelDate / WheelHour / WheelMinute / WheelPeriod / WheelIndicator / WheelMask

Column and overlay parts aliasing the matching WheelDateTimePicker parts. Use them to customize column order, content, and styling inside DateTimePicker.Wheel.

DateTimePickerNew