Date Input

A segment-based date input that allows users to enter dates by navigating individual date parts.

Date

mmddyyyy

Anatomy

<DateInput.Root>
  <DateInput.Label />
  <DateInput.Control>
    <DateInput.SegmentGroup>
      <DateInput.Segment />
    </DateInput.SegmentGroup>
  </DateInput.Control>
  <DateInput.HiddenInput />
</DateInput.Root>

Examples

Default Value

Use the defaultValue prop with parseDate to set the initial date value.

Controlled

Use the value and onValueChange props to control the date input's value programmatically.

Root Provider

An alternative way to control the date input is to use the RootProvider component and the useDateInput hook. This way you can access the state and methods from outside the component.

Granularity

Use the granularity prop to control which date fields are displayed. Supported values are day, hour, minute, and second.

Time Only

To create a time-only input, set granularity to minute (or second) and provide a formatter that only includes time fields. Use the hourCycle prop to switch between 12 and 24 hour formats.

Range

To create a date input that allows a range selection, set the selectionMode prop to range and render two SegmentGroup components with index props set to 0 and 1.

Min and Max

Use the min and max props with parseDate to restrict the selectable date range. Dates outside this range will be marked as invalid.

Disabled

Use the disabled prop to prevent user interaction with the date input.

Read Only

Use the readOnly prop to make the date input non-editable while still being focusable.

Invalid

Use the invalid prop to indicate an error state on the date input.

Leading Zeros

Use the shouldForceLeadingZeros prop to toggle whether numeric segments are padded with a leading zero.

Localized

Use the locale prop to set the language and regional formatting of the date segments.

RTL

Set the dir prop to rtl for right-to-left language support.

With Clear Button

Use useDateInput via RootProvider to access the clearValue method and render a clear button alongside the input.

With Date Picker

Combine DateInput with DatePicker by syncing their values using onValueChange to provide both typed and calendar-based date selection.

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`allSegments`		`Partial<{ year: boolean month: boolean day: boolean hour: boolean minute: boolean second: boolean dayPeriod: boolean era: boolean literal: boolean timeZoneName: boolean weekday: boolean unknown: boolean fractionalSecond: boolean }>` The computed segments map for the formatter.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`createCalendar`		`(identifier: CalendarIdentifier) => Calendar` A function that creates a calendar object for a given calendar identifier. Use this to support non-Gregorian calendars (e.g., Persian, Islamic, Buddhist).
`defaultPlaceholderValue`		`DateValue` The initial placeholder date when rendered.
`defaultValue`		`DateValue[]` The initial selected date(s) when rendered. Use when you don't need to control the selected date(s).
`dir`	`'ltr'`	`'ltr' \| 'rtl'` The document's text/writing direction.
`disabled`		`boolean` Whether the date input is disabled.
`form`		`string` The `form` attribute of the hidden input element.
`format`		`(date: DateValue, details: FormatDateDetails) => string` The format function for converting a DateValue to a string.
`formatter`		`DateFormatter` The date formatter to use.
`getRootNode`		`() => ShadowRoot \| Node \| Document` A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
`granularity`	`'day'`	`DateGranularity` Determines the smallest unit that is displayed in the date input.
`hideTimeZone`	`false`	`boolean` Whether to hide the time zone segment when the value is a `ZonedDateTime`. Has no effect for values without a time zone.
`hourCycle`		`HourCycle` Whether to use 12-hour or 24-hour time format. By default, this is determined by the locale.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string label: (index: number) => string control: string segmentGroup: (index: number) => string hiddenInput: (index: number) => string }>` The ids of the elements in the date input. Useful for composition.
`invalid`		`boolean` Whether the date input is invalid
`isDateUnavailable`		`(date: DateValue, locale: string) => boolean` Returns whether a date is unavailable. When a committed date matches, the input is marked as invalid.
`locale`	`'en-US'`	`string` The locale (BCP 47 language tag) to use when formatting the date.
`max`		`DateValue` The maximum date that can be selected.
`min`		`DateValue` The minimum date that can be selected.
`name`		`string` The `name` attribute of the input element.
`onFocusChange`		`(details: FocusChangeDetails) => void` A function called when the date input gains or loses focus.
`onPlaceholderChange`		`(details: PlaceholderChangeDetails) => void` A function called when the placeholder value changes.
`onValueChange`		`(details: ValueChangeDetails) => void` Function called when the value changes.
`placeholderValue`		`DateValue` The controlled placeholder date.
`readOnly`		`boolean` Whether the date input is read-only.
`required`		`boolean` Whether the date input is required
`selectionMode`	`'single'`	`SelectionMode` The selection mode of the date input. - `single` - only one date can be entered - `range` - a range of dates can be entered (start and end)
`shouldForceLeadingZeros`	`false`	`boolean` Whether to always show leading zeros in month, day, and hour fields. When false, formatting follows the locale default (e.g. "1" instead of "01").
`timeZone`	`'UTC'`	`string` The time zone to use
`translations`		`IntlTranslations` The localized messages to use.
`value`		`DateValue[]` The controlled selected date(s).

Attribute	Description
`[data-scope]`	date-input
`[data-part]`	root
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid

Control

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	date-input
`[data-part]`	control
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid
`[data-focus]`	Present when focused

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`index`		`number`

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	date-input
`[data-part]`	label
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`DateInputApi<PropTypes>`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

SegmentGroup

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`index`		`number`

Attribute	Description
`[data-scope]`	date-input
`[data-part]`	segment-group
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid
`[data-focus]`	Present when focused

Segment

Renders a <span> element.

Prop	Default	Type
`segment`		`DateSegment`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	date-input
`[data-part]`	segment
`[data-type]`	The type of the item
`[data-readonly]`	Present when read-only
`[data-disabled]`	Present when disabled
`[data-value]`	The value of the item
`[data-editable]`
`[data-placeholder-shown]`	Present when placeholder is shown

Context

API

Property	Type
`focused`	`boolean` Whether the date input is focused
`disabled`	`boolean` Whether the date input is disabled
`invalid`	`boolean` Whether the date input is invalid
`value`	`DateValue[]` The selected date(s).
`valueAsDate`	`Date[]` The selected date(s) as Date objects.
`valueAsString`	`string[]` The selected date(s) as strings.
`placeholderValue`	`DateValue` The placeholder date.
`displayValues`	`IncompleteDate[]` Per-group editing state. Each IncompleteDate tracks which segments have been filled in by the user (non-null = entered, null = placeholder).
`focus`	`VoidFunction` Focuses the first segment.
`setValue`	`(values: DateValue[]) => void` Sets the selected date(s) to the given values.
`clearValue`	`VoidFunction` Clears the selected date(s).
`getSegments`	`(props?: SegmentsProps \| undefined) => DateSegment[]` Returns the segments for the given index.
`getSegmentState`	`(props: SegmentProps) => SegmentState` Returns the state details for a given segment.

Accessibility

Complies with the Spinbutton WAI-ARIA design pattern.