Date Picker

A component that allows users to select a date from a calendar.

Date Picker

You can explore the date-picker component in the following curated examples.

Standalone Date Picker

Perfect for use cases like booking systems or holiday selection.

Anatomy

<DatePicker.Root>
  <DatePicker.Label />
  <DatePicker.Control>
    <DatePicker.Input />
    <DatePicker.Trigger />
    <DatePicker.ClearTrigger />
  </DatePicker.Control>
  <DatePicker.Positioner>
    <DatePicker.Content>
      <DatePicker.View>
        <DatePicker.ViewControl>
          <DatePicker.PrevTrigger />
          <DatePicker.ViewTrigger>
            <DatePicker.RangeText />
          </DatePicker.ViewTrigger>
          <DatePicker.NextTrigger />
        </DatePicker.ViewControl>
        <DatePicker.Table>
          <DatePicker.TableHead>
            <DatePicker.TableRow>
              <DatePicker.TableHeader />
            </DatePicker.TableRow>
          </DatePicker.TableHead>
          <DatePicker.TableBody>
            <DatePicker.TableRow>
              <DatePicker.TableCell>
                <DatePicker.TableCellTrigger />
              </DatePicker.TableCell>
            </DatePicker.TableRow>
          </DatePicker.TableBody>
        </DatePicker.Table>
      </DatePicker.View>
    </DatePicker.Content>
  </DatePicker.Positioner>
</DatePicker.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 picker's value programmatically.

Root Provider

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

Default View

Use the defaultView prop to set which view (day, month, or year) the calendar opens to initially.

Month and Year Select

Use MonthSelect and YearSelect components to create a header with dropdown selects for quick month/year navigation, alongside the prev/next triggers.

Range

To create a date picker that allows a range selection, you need to:

Set the selectionMode prop to range.
Render multiple inputs with the index prop set to 0 and 1.

Multiple

Use the selectionMode="multiple" prop to allow selecting multiple dates. This example also shows how to display selected dates as removable tags.

Multiple Months

To create a date picker that displays multiple months side by side:

Set the numOfMonths prop to the number of months you want to display.
Use the datePicker.getOffset({ months: 1 }) to get data for the next month.

Presets

Use the DatePicker.PresetTrigger component to add quick-select preset options like "Last 7 days" or "This month".

Min and Max

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

Unavailable

Use the isDateUnavailable prop to mark specific dates as unavailable. This example disables weekends.

Locale

Use the locale prop to set the language and formatting, and startOfWeek to set the first day of the week (0 = Sunday, 1 = Monday, etc.).

Month Picker

Create a month-only picker by setting defaultView="month" and minView="month". Use custom format and parse functions to handle month/year input format.

Year Picker

Create a year-only picker by setting defaultView="year" and minView="year". Use custom format and parse functions to handle year-only input format.

Inline

Use the inline prop to display the date picker directly on the page, without a popup.

When using the inline prop, omit the Portal, Positioner, and Content components to render the calendar inline within your layout.

Custom Parsing

Use the parse prop to implement custom date parsing logic. This allows users to enter dates in flexible formats like "25/12" or "25/12/24" which are automatically converted to valid dates.

Month Picker Range

Create a month range picker by combining selectionMode="range" with defaultView="month" and minView="month". This is useful for selecting billing periods or date ranges by month.

Year Range

Create a year range picker by combining selectionMode="range" with defaultView="year" and minView="year". This is useful for selecting multi-year periods.

With Time

Integrate a time input with the date picker using CalendarDateTime from @internationalized/date. The time input updates the hour and minute of the selected date value.

API Reference

Props

Root

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.
`closeOnSelect`	`true`	`boolean` Whether the calendar should close after the date selection is complete. This is ignored when the selection mode is `multiple`.
`defaultFocusedValue`		`DateValue` The initial focused date when rendered. Use when you don't need to control the focused date of the date picker.
`defaultOpen`		`boolean` The initial open state of the date picker when rendered. Use when you don't need to control the open state of the date picker.
`defaultValue`		`DateValue[]` The initial selected date(s) when rendered. Use when you don't need to control the selected date(s) of the date picker.
`defaultView`	`'day'`	`DateView` The default view of the calendar
`disabled`		`boolean` Whether the calendar is disabled.
`fixedWeeks`		`boolean` Whether the calendar should have a fixed number of weeks. This renders the calendar with 6 weeks instead of 5 or 6.
`focusedValue`		`DateValue` The controlled focused date.
`format`		`(date: DateValue, details: LocaleDetails) => string` The format of the date to display in the input.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string; label: (index: number) => string; table: (id: string) => string; tableHeader: (id: string) => string; tableBody: (id: string) => string; tableRow: (id: string) => string; content: string; ... 10 more ...; positioner: string; }>` The ids of the elements in the date picker. Useful for composition.
`immediate`		`boolean` Whether to synchronize the present change immediately or defer it to the next frame
`inline`		`boolean` Whether to render the date picker inline
`isDateUnavailable`		`(date: DateValue, locale: string) => boolean` Returns whether a date of the calendar is available.
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting
`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.
`maxView`	`'year'`	`DateView` The maximum view of the calendar
`min`		`DateValue` The minimum date that can be selected.
`minView`	`'day'`	`DateView` The minimum view of the calendar
`name`		`string` The `name` attribute of the input element.
`numOfMonths`		`number` The number of months to display.
`onExitComplete`		`VoidFunction` Function called when the animation ends in the closed state
`onFocusChange`		`(details: FocusChangeDetails) => void` Function called when the focused date changes.
`onOpenChange`		`(details: OpenChangeDetails) => void` Function called when the calendar opens or closes.
`onValueChange`		`(details: ValueChangeDetails) => void` Function called when the value changes.
`onViewChange`		`(details: ViewChangeDetails) => void` Function called when the view changes.
`open`		`boolean` The controlled open state of the date picker
`outsideDaySelectable`	`false`	`boolean` Whether day outside the visible range can be selected.
`parse`		`(value: string, details: LocaleDetails) => DateValue \| undefined` Function to parse the date from the input back to a DateValue.
`placeholder`		`string` The placeholder text to display in the input.
`positioning`		`PositioningOptions` The user provided options used to position the date picker content
`present`		`boolean` Whether the node is present (controlled by the user)
`readOnly`		`boolean` Whether the calendar is read-only.
`selectionMode`	`'single'`	`SelectionMode` The selection mode of the calendar. - `single` - only one date can be selected - `multiple` - multiple dates can be selected - `range` - a range of dates can be selected
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`startOfWeek`		`number` The first day of the week. `0` - Sunday `1` - Monday `2` - Tuesday `3` - Wednesday `4` - Thursday `5` - Friday `6` - Saturday
`timeZone`	`'UTC'`	`string` The time zone to use
`translations`		`IntlTranslations` The localized messages to use.
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.
`value`		`DateValue[]` The controlled selected date(s).
`view`		`DateView` The view of the calendar

Attribute	Description
`[data-scope]`	date-picker
`[data-part]`	root
`[data-state]`	"open" \| "closed"
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only

ClearTrigger

Renders a <button> 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.

Content

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-picker
`[data-part]`	content
`[data-state]`	"open" \| "closed"
`[data-nested]`	popover
`[data-has-nested]`	popover
`[data-placement]`	The placement of the content
`[data-inline]`	Present when the content is inline

CSS Variable	Description
`--layer-index`	The index of the dismissable in the layer stack
`--nested-layer-count`	The number of nested date-pickers

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-picker
`[data-part]`	control
`[data-disabled]`	Present when disabled

Input

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.
`fixOnBlur`	`true`	`boolean` Whether to fix the input value on blur.
`index`		`number` The index of the input to focus.

Attribute	Description
`[data-scope]`	date-picker
`[data-part]`	input
`[data-index]`	The index of the item
`[data-state]`	"open" \| "closed"
`[data-invalid]`	Present when invalid

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-picker
`[data-part]`	label
`[data-state]`	"open" \| "closed"
`[data-index]`	The index of the item
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only

MonthSelect

Renders a <select> 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.

NextTrigger

Renders a <button> 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-picker
`[data-part]`	next-trigger
`[data-disabled]`	Present when disabled

Positioner

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.

CSS Variable	Description
`--reference-width`	The width of the reference element
`--reference-height`	The height of the root
`--available-width`	The available width in viewport
`--available-height`	The available height in viewport
`--x`	The x position for transform
`--y`	The y position for transform
`--z-index`	The z-index value
`--transform-origin`	The transform origin for animations

PresetTrigger

Renders a <button> element.

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

PrevTrigger

Renders a <button> 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-picker
`[data-part]`	prev-trigger
`[data-disabled]`	Present when disabled

RangeText

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.

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseDatePickerReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`immediate`		`boolean` Whether to synchronize the present change immediately or defer it to the next frame
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting
`onExitComplete`		`VoidFunction` Function called when the animation ends in the closed state
`present`		`boolean` Whether the node is present (controlled by the user)
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.

TableBody

Renders a <tbody> 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-picker
`[data-part]`	table-body
`[data-view]`	The view of the tablebody
`[data-disabled]`	Present when disabled

TableCell

Renders a <td> element.

Prop	Default	Type
`value`		`number \| DateValue`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`columns`		`number`
`disabled`		`boolean`
`visibleRange`		`VisibleRange`

TableCellTrigger

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.

TableHead

Renders a <tbody> 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-picker
`[data-part]`	table-head
`[data-view]`	The view of the tablehead
`[data-disabled]`	Present when disabled

TableHeader

Renders a <td> 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-picker
`[data-part]`	table-header
`[data-view]`	The view of the tableheader
`[data-disabled]`	Present when disabled

Table

Renders a <table> 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.
`columns`		`number`

Attribute	Description
`[data-scope]`	date-picker
`[data-part]`	table
`[data-columns]`
`[data-view]`	The view of the table

TableRow

Renders a <tr> 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-picker
`[data-part]`	table-row
`[data-disabled]`	Present when disabled
`[data-view]`	The view of the tablerow

Trigger

Renders a <button> 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-picker
`[data-part]`	trigger
`[data-placement]`	The placement of the trigger
`[data-state]`	"open" \| "closed"

ViewControl

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-picker
`[data-part]`	view-control
`[data-view]`	The view of the viewcontrol

View

Renders a <div> element.

Prop	Default	Type
`view`		`DateView`
`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-picker
`[data-part]`	view
`[data-view]`	The view of the view

ViewTrigger

Renders a <button> 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-picker
`[data-part]`	view-trigger
`[data-view]`	The view of the viewtrigger

YearSelect

Renders a <select> 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.

Context

API

Property	Type
`focused`	`boolean` Whether the input is focused
`open`	`boolean` Whether the date picker is open
`disabled`	`boolean` Whether the date picker is disabled
`invalid`	`boolean` Whether the date picker is invalid
`inline`	`boolean` Whether the date picker is rendered inline
`view`	`DateView` The current view of the date picker
`getDaysInWeek`	`(week: number, from?: DateValue) => DateValue[]` Returns an array of days in the week index counted from the provided start date, or the first visible date if not given.
`getOffset`	`(duration: DateDuration) => DateValueOffset` Returns the offset of the month based on the provided number of months.
`getRangePresetValue`	`(value: DateRangePreset) => DateValue[]` Returns the range of dates based on the provided date range preset.
`getMonthWeeks`	`(from?: DateValue) => DateValue[][]` Returns the weeks of the month from the provided date. Represented as an array of arrays of dates.
`isUnavailable`	`(date: DateValue) => boolean` Returns whether the provided date is available (or can be selected)
`weeks`	`DateValue[][]` The weeks of the month. Represented as an array of arrays of dates.
`weekDays`	`WeekDay[]` The days of the week. Represented as an array of strings.
`visibleRange`	`VisibleRange` The visible range of dates.
`visibleRangeText`	`VisibleRangeText` The human readable text for the visible range of dates.
`value`	`DateValue[]` The selected date.
`valueAsDate`	`Date[]` The selected date as a Date object.
`valueAsString`	`string[]` The selected date as a string.
`focusedValue`	`DateValue` The focused date.
`focusedValueAsDate`	`Date` The focused date as a Date object.
`focusedValueAsString`	`string` The focused date as a string.
`selectToday`	`VoidFunction` Sets the selected date to today.
`setValue`	`(values: DateValue[]) => void` Sets the selected date to the given date.
`setFocusedValue`	`(value: DateValue) => void` Sets the focused date to the given date.
`clearValue`	`VoidFunction` Clears the selected date(s).
`setOpen`	`(open: boolean) => void` Function to open or close the calendar.
`focusMonth`	`(month: number) => void` Function to set the selected month.
`focusYear`	`(year: number) => void` Function to set the selected year.
`getYears`	`() => Cell[]` Returns the months of the year
`getYearsGrid`	`(props?: YearGridProps) => YearGridValue` Returns the years of the decade based on the columns. Represented as an array of arrays of years.
`getDecade`	`() => Range<number>` Returns the start and end years of the decade.
`getMonths`	`(props?: MonthFormatOptions) => Cell[]` Returns the months of the year
`getMonthsGrid`	`(props?: MonthGridProps) => MonthGridValue` Returns the months of the year based on the columns. Represented as an array of arrays of months.
`format`	`(value: DateValue, opts?: Intl.DateTimeFormatOptions) => string` Formats the given date value based on the provided options.
`setView`	`(view: DateView) => void` Sets the view of the date picker.
`goToNext`	`VoidFunction` Goes to the next month/year/decade.
`goToPrev`	`VoidFunction` Goes to the previous month/year/decade.
`getDayTableCellState`	`(props: DayTableCellProps) => DayTableCellState` Returns the state details for a given cell.
`getMonthTableCellState`	`(props: TableCellProps) => TableCellState` Returns the state details for a given month cell.
`getYearTableCellState`	`(props: TableCellProps) => TableCellState` Returns the state details for a given year cell.

Accessibility

Keyboard Support

Key	Description
`ArrowLeft`	Moves focus to the previous day within the current week.
`ArrowRight`	Moves focus to the next day within the current week.
`ArrowUp`	Moves focus to the same day of the week in the previous week.
`ArrowDown`	Moves focus to the same day of the week in the next week.
`Home`	Moves focus to the first day of the current month.
`End`	Moves focus to the last day of the current month.
`PageUp`	Moves focus to the same day of the month in the previous month.
`PageDown`	Moves focus to the same day of the month in the next month.
`Enter`	Selects the focused date and closes the date picker.
`Esc`	Closes the date picker without selecting any date.