HeroUI Pro
Getting Started
Components
Releases

DateField

A date input field with `dd/mm/yyyy` masking and an optional calendar popup for selecting dates.

Import

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

Anatomy

<DateField>
  <Label>...</Label>
  <DateField.InputGroup>
    <DateField.Input />
    <DateField.Suffix>
      <DateField.Select>
        <DateField.Trigger>
          <DateField.TriggerIndicator />
        </DateField.Trigger>
        <DateField.Portal>
          <DateField.Overlay />
          <DateField.Content>
            <DateField.Calendar>
              <Calendar.Header>...</Calendar.Header>
              <Calendar.Grid>...</Calendar.Grid>
            </DateField.Calendar>
          </DateField.Content>
        </DateField.Portal>
      </DateField.Select>
    </DateField.Suffix>
  </DateField.InputGroup>
  <Description>...</Description>
</DateField>
  • DateField: Root container that manages date selection state, open state, input masking mode, and form field context (for Label, Description, FieldError). Supports controlled and uncontrolled modes.
  • DateField.InputGroup: Input group wrapper that contains the text input, prefix, and suffix slots.
  • DateField.Input: Text input with dd/mm/yyyy masked entry. In "masked" mode, digits auto-insert / separators and blur commits the parsed date. In "loose" mode, no masking or parse is applied. Selecting a date in the calendar updates the input text.
  • DateField.Prefix: Optional leading slot inside the input group.
  • DateField.Suffix: Trailing slot inside the input group. Typically contains the calendar trigger.
  • DateField.Select: Pre-wired Select root connected to the DateField context. State props are managed by the root.
  • DateField.Trigger: Pressable trigger that opens the calendar overlay. Automatically dismisses the keyboard on press.
  • DateField.TriggerIndicator: Indicator icon inside the trigger. Defaults to a calendar icon with a muted background.
  • DateField.Portal: Portal wrapper that re-provides DateField context across the portal boundary.
  • DateField.Overlay: Backdrop overlay behind the calendar content.
  • DateField.Content: Content container for the calendar popup. Supports "popover", "dialog", and "bottom-sheet" presentations.
  • DateField.Calendar: Pre-wired Calendar root that commits the selected date, updates the input text, and closes the overlay on selection. Uses Calendar compound parts as children.

Usage

Basic Usage

The DateField uses masked input by default. Digits auto-insert / separators toward dd/mm/yyyy. Blur commits the parsed date.

<DateField>
  <Label>Event date</Label>
  <DateField.InputGroup>
    <DateField.Input />
    <DateField.Suffix>
      <DateField.Select presentation="bottom-sheet">
        <DateField.Trigger>
          <DateField.TriggerIndicator />
        </DateField.Trigger>
        <DateField.Portal>
          <DateField.Overlay />
          <DateField.Content presentation="bottom-sheet">
            <DateField.Calendar>
              <Calendar.Header>
                <Calendar.Heading />
                <Calendar.NavButton slot="previous" />
                <Calendar.NavButton slot="next" />
              </Calendar.Header>
              <Calendar.Grid>
                <Calendar.GridHeader>
                  {(day) => <Calendar.HeaderCell day={day} />}
                </Calendar.GridHeader>
                <Calendar.GridBody>
                  {(date) => <Calendar.Cell date={date} />}
                </Calendar.GridBody>
              </Calendar.Grid>
            </DateField.Calendar>
          </DateField.Content>
        </DateField.Portal>
      </DateField.Select>
    </DateField.Suffix>
  </DateField.InputGroup>
  <Description>The field formats as dd/mm/yyyy.</Description>
</DateField>

Loose Input Mode

Set inputMode="loose" for plain text without masking or blur parsing. The calendar still updates the input when a date is selected.

<DateField inputMode="loose">
  <Label>Event date</Label>
  <DateField.InputGroup>
    <DateField.Input />
    <DateField.Suffix>
      <DateField.Select>
        <DateField.Trigger>
          <DateField.TriggerIndicator />
        </DateField.Trigger>
        <DateField.Portal>
          <DateField.Overlay />
          <DateField.Content presentation="popover" width="full">
            <DateField.Calendar>...</DateField.Calendar>
          </DateField.Content>
        </DateField.Portal>
      </DateField.Select>
    </DateField.Suffix>
  </DateField.InputGroup>
</DateField>

Popover Presentation

Display the calendar in a popover anchored to the trigger.

<DateField>
  <Label>Ship date</Label>
  <DateField.InputGroup>
    <DateField.Input />
    <DateField.Suffix>
      <DateField.Select>
        <DateField.Trigger>
          <DateField.TriggerIndicator />
        </DateField.Trigger>
        <DateField.Portal>
          <DateField.Overlay />
          <DateField.Content presentation="popover" width="full">
            <DateField.Calendar>...</DateField.Calendar>
          </DateField.Content>
        </DateField.Portal>
      </DateField.Select>
    </DateField.Suffix>
  </DateField.InputGroup>
</DateField>

Dialog Presentation

Display the calendar in a centered modal dialog.

<DateField>
  <Label>Return by</Label>
  <DateField.InputGroup>
    <DateField.Input />
    <DateField.Suffix>
      <DateField.Select presentation="dialog">
        <DateField.Trigger>
          <DateField.TriggerIndicator />
        </DateField.Trigger>
        <DateField.Portal>
          <DateField.Overlay />
          <DateField.Content presentation="dialog">
            <DateField.Calendar>...</DateField.Calendar>
          </DateField.Content>
        </DateField.Portal>
      </DateField.Select>
    </DateField.Suffix>
  </DateField.InputGroup>
</DateField>

Field States

Use root props for required, invalid, and disabled states.

<DateField isRequired>
  <Label>Ship date</Label>
  <DateField.InputGroup>
    <DateField.Input />
    <DateField.Suffix>
      <DateField.Select>
        <DateField.Trigger>
          <DateField.TriggerIndicator />
        </DateField.Trigger>
        <DateField.Portal>
          <DateField.Overlay />
          <DateField.Content presentation="popover" width="full">
            <DateField.Calendar>...</DateField.Calendar>
          </DateField.Content>
        </DateField.Portal>
      </DateField.Select>
    </DateField.Suffix>
  </DateField.InputGroup>
  <Description>Required for logistics.</Description>
</DateField>

Invalid State with FieldError

Combine isInvalid with FieldError to display validation messages.

<DateField isInvalid>
  <Label>Return by</Label>
  <DateField.InputGroup>
    <DateField.Input />
    <DateField.Suffix>
      <DateField.Select presentation="dialog">
        <DateField.Trigger>
          <DateField.TriggerIndicator />
        </DateField.Trigger>
        <DateField.Portal>
          <DateField.Overlay />
          <DateField.Content presentation="dialog">
            <DateField.Calendar>...</DateField.Calendar>
          </DateField.Content>
        </DateField.Portal>
      </DateField.Select>
    </DateField.Suffix>
  </DateField.InputGroup>
  <Description hideOnInvalid>Must be a business day.</Description>
  <FieldError>Please enter a valid return date.</FieldError>
</DateField>

Example

import { Description, FieldError, Label } from 'heroui-native';
import { Calendar, DateField } from 'heroui-native-pro';
import { View } from 'react-native';

export default function DateFieldExample() {
  return (
    <View className="flex-1 justify-center px-5 gap-12">
      <DateField inputMode="masked">
        <Label>Event date (masked)</Label>
        <DateField.InputGroup>
          <DateField.Input />
          <DateField.Suffix>
            <DateField.Select presentation="bottom-sheet">
              <DateField.Trigger>
                <DateField.TriggerIndicator />
              </DateField.Trigger>
              <DateField.Portal>
                <DateField.Overlay />
                <DateField.Content presentation="bottom-sheet">
                  <DateField.Calendar>
                    <Calendar.Header>
                      <Calendar.Heading />
                      <Calendar.NavButton slot="previous" />
                      <Calendar.NavButton slot="next" />
                    </Calendar.Header>
                    <Calendar.Grid>
                      <Calendar.GridHeader>
                        {(day) => <Calendar.HeaderCell day={day} />}
                      </Calendar.GridHeader>
                      <Calendar.GridBody>
                        {(date) => <Calendar.Cell date={date} />}
                      </Calendar.GridBody>
                    </Calendar.Grid>
                  </DateField.Calendar>
                </DateField.Content>
              </DateField.Portal>
            </DateField.Select>
          </DateField.Suffix>
        </DateField.InputGroup>
        <Description>The field formats as dd/mm/yyyy.</Description>
      </DateField>

      <DateField isInvalid>
        <Label>Return by</Label>
        <DateField.InputGroup>
          <DateField.Input />
          <DateField.Suffix>
            <DateField.Select presentation="dialog">
              <DateField.Trigger>
                <DateField.TriggerIndicator />
              </DateField.Trigger>
              <DateField.Portal>
                <DateField.Overlay />
                <DateField.Content presentation="dialog">
                  <DateField.Calendar>
                    <Calendar.Header>
                      <Calendar.Heading />
                      <Calendar.NavButton slot="previous" />
                      <Calendar.NavButton slot="next" />
                    </Calendar.Header>
                    <Calendar.Grid>
                      <Calendar.GridHeader>
                        {(day) => <Calendar.HeaderCell day={day} />}
                      </Calendar.GridHeader>
                      <Calendar.GridBody>
                        {(date) => <Calendar.Cell date={date} />}
                      </Calendar.GridBody>
                    </Calendar.Grid>
                  </DateField.Calendar>
                </DateField.Content>
              </DateField.Portal>
            </DateField.Select>
          </DateField.Suffix>
        </DateField.InputGroup>
        <Description hideOnInvalid>Must be a business day.</Description>
        <FieldError>Please enter a valid return date.</FieldError>
      </DateField>
    </View>
  );
}

API Reference

DateField

proptypedefaultdescription
childrenReact.ReactNode-Children elements (Label, DateField.InputGroup, Description, FieldError)
valueDateFieldOption-Controlled selected option
defaultValueDateFieldOption-Default selected option for uncontrolled usage
inputModeDateFieldInputMode'masked'Input keyboard behavior
isDisabledbooleanfalseWhether the entire field is disabled
isInvalidbooleanfalseWhether the field is in an invalid state
isRequiredbooleanfalseWhether the field is required
isOpenboolean-Controlled open state of the calendar overlay
isDefaultOpenboolean-Initial open state for uncontrolled usage
localestring-BCP 47 locale forwarded to DateField.Calendar
classNamestring-Additional CSS classes for the root container
animationAnimationRootDisableAll-Animation configuration for the date field subtree
onValueChange(value: DateFieldOption | undefined) => void-Handler called when the selected option changes
onOpenChange(open: boolean) => void-Handler called when the open state changes
...ViewPropsViewProps-All standard React Native View props are supported

DateFieldOption

propertytypedescription
valuestringISO date string (e.g. "2026-06-15")
labelstringDisplay string (e.g. "15/06/2026")

DateFieldInputMode

Input keyboard behavior for DateField.Input:

  • 'masked' — Digits only, auto-inserts / toward dd/mm/yyyy. Blur commits the parsed date. maxLength is set to 10. (default)
  • 'loose' — Plain text, no masking or blur parsing. The calendar still updates the field on selection.

AnimationRootDisableAll

Animation configuration for the DateField root. Can be:

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

DateField.InputGroup

proptypedefaultdescription
childrenReact.ReactNode-Input group content (Input, Prefix, Suffix)
classNamestring-Additional CSS classes
...ViewPropsViewProps-All standard React Native View props are supported

DateField.Input

proptypedefaultdescription
placeholderstring'dd/mm/yyyy'Placeholder text shown when the input is empty
inputModestring'numeric'Keyboard type for the text input
isDisabledboolean-Whether the input is disabled; inherits from root when omitted
maxLengthnumber10Maximum character length; auto-set to 10 in masked mode
onChangeText(text: string) => void-Side-effect handler called after the internal masked change handler
onBlur(e: BlurEvent) => void-Side-effect handler called after the internal blur commit
...InputPropsInputGroupInputProps-All InputGroup.Input props are supported except value and onChangeText

DateField.Prefix

proptypedefaultdescription
childrenReact.ReactNode-Prefix content
classNamestring-Additional CSS classes
...ViewPropsViewProps-All standard React Native View props are supported

DateField.Suffix

proptypedefaultdescription
childrenReact.ReactNode-Suffix content (typically the calendar trigger)
classNamestring-Additional CSS classes
...ViewPropsViewProps-All standard React Native View props are supported

DateField.Select

proptypedefaultdescription
childrenReact.ReactNode-Select content (Trigger, Portal)
isDisabledboolean-Overrides the root isDisabled when set
presentation'popover' | 'dialog' | 'bottom-sheet''popover'Presentation mode for the select content
classNamestring-Additional CSS classes
...ViewPropsViewProps-All standard React Native View props are supported

DateField.Trigger

proptypedefaultdescription
childrenReact.ReactNode-Trigger content (TriggerIndicator)
variant'default' | 'unstyled''unstyled'Trigger styling variant
isDisabledboolean-Whether the trigger is disabled
classNamestring-Additional CSS classes for the trigger
onPress(e: GestureResponderEvent) => void-Press handler; keyboard is dismissed before this fires
...PressablePropsPressableProps-All standard React Native Pressable props are supported

DateField.TriggerIndicator

proptypedefaultdescription
childrenReact.ReactNode-Custom indicator content; defaults to a calendar icon when omitted
iconPropsSelectTriggerIndicatorIconProps-Overrides for the default icon
isAnimatedStyleActivebooleanfalseWhether animated rotation styles are applied
classNamestring-Additional CSS classes for the indicator container
animationSelectTriggerIndicatorAnimationfalseRotation animation configuration; disabled by default
...ViewPropsViewProps-All standard React Native View props are supported

SelectTriggerIndicatorIconProps

proptypedefaultdescription
sizenumber16Icon size in logical pixels
colorstringmutedIcon fill color

DateField.Portal

proptypedefaultdescription
childrenReact.ReactNode-Portal content (Overlay, Content)
hostNamestring-Optional name of the host element for the portal
disableFullWindowOverlaybooleanfalseUse a regular View instead of FullWindowOverlay on iOS
unstable_accessibilityContainerViewIsModalbooleanfalseControls whether VoiceOver treats the overlay as a modal container (iOS)
classNamestring-Additional CSS classes for the portal container

DateField.Overlay

proptypedefaultdescription
closeOnPressbooleantrueWhether to close the picker when the overlay is pressed
isAnimatedStyleActivebooleantrueWhether animated opacity styles are applied
classNamestring-Additional CSS classes for the overlay backdrop
animationSelectOverlayAnimation-Opacity animation configuration
...PressablePropsPressableProps-All standard React Native Pressable props are supported

DateField.Content

The content component is a union type based on the presentation prop.

Popover presentation

proptypedefaultdescription
childrenReact.ReactNode-Content (DateField.Calendar)
presentation'popover'-Popover presentation mode
width'content-fit' | 'trigger' | 'full' | number'content-fit'Content width sizing strategy
classNamestring-Additional CSS classes for the content container
animationSelectContentPopoverAnimation-Keyframe animation configuration for entering/exiting
...ViewPropsViewProps-All standard React Native View props are supported

Dialog presentation

proptypedefaultdescription
childrenReact.ReactNode-Content (DateField.Calendar)
presentation'dialog'-Dialog presentation mode
isSwipeablebooleantrueWhether the dialog can be swiped to dismiss
classNamestring-Additional CSS classes for the content container
animationSelectContentAnimation-Keyframe animation configuration for scale/opacity
...ViewPropsViewProps-All standard React Native View props are supported

Bottom sheet presentation

proptypedefaultdescription
childrenReact.ReactNode-Content (DateField.Calendar)
presentation'bottom-sheet'-Bottom sheet presentation mode
...BottomSheetPropsBottomSheetProps-All @gorhom/bottom-sheet props are supported

DateField.Calendar

proptypedefaultdescription
childrenReact.ReactNode-Calendar compound parts (Calendar.Header, Calendar.Grid, etc.)
valueDateValue | null-Overrides the calendar value derived from the root selection
localestring-Overrides the root locale for the calendar grid
accessibilityLabelstring'Pick a date'Screen reader label for the calendar container
onChange(date: DateValue) => void-Side-effect handler called before the default commit behavior
...CalendarPropsCalendarProps-All Calendar root props are supported (minValue, maxValue, etc.)

Hooks

useDateField

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

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

const { inputMode, inputText, onInputChangeText, onInputBlur } = useDateField();

Returns: DateFieldInputContextValue

propertytypedescription
inputModeDateFieldInputModeCurrent input mode ("masked" or "loose")
inputTextstringCurrent draft text in the input
onInputChangeText(text: string) => voidUpdate the draft text; in masked mode, applies dd/mm/yyyy formatting
onInputBlur() => voidCommit the draft text on blur; in masked mode, parses and updates the picker value

Calendar

A single-date calendar for selecting dates with month navigation, locale support, and customizable day cells.

DatePicker

A single-date picker that combines a trigger field with a calendar popup for selecting dates.

On this page

ImportAnatomyUsageBasic UsageLoose Input ModePopover PresentationDialog PresentationField StatesInvalid State with FieldErrorExampleAPI ReferenceDateFieldDateFieldOptionDateFieldInputModeAnimationRootDisableAllDateField.InputGroupDateField.InputDateField.PrefixDateField.SuffixDateField.SelectDateField.TriggerDateField.TriggerIndicatorSelectTriggerIndicatorIconPropsDateField.PortalDateField.OverlayDateField.ContentPopover presentationDialog presentationBottom sheet presentationDateField.CalendarHooksuseDateFieldReturns: DateFieldInputContextValue