1. framework components
  2. date picker

Date Picker

Select dates from a calendar interface.

Warning

This feature is currently marked as beta and not intended for production use. It may receive breaking changes before its stable release.

Usage

Given the scale and scope of the Date Picker component, consider implementing within a local component to add a layer of abstraction. Then utlize the props and event handlers to pass data to and from the component respectively.

Controlled

Manage the selected date value with controlled state.

Disabled

Disable the date picker to prevent user interaction.

Minimum and Maximum

Restrict date selection to a specific range using the min and max props with the parseDate helper function.

Range Selection

Enable range selection by setting selectionMode="range" on the root component. Pair with two inputs fields:

  • index={0} to represent the start dates.
  • index={1} to represent the end dates.

Inline calendar

Display the calendar inline without a popover by adding the inline prop to the root component. When using inline mode, omit the Portal and Positioner components.

26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
1
2
3
4
5
6

Month and Year Selection

Add MonthSelect and YearSelect components to provide selectors for quickly changing the month and year.

API Reference

Root

txt
flex flex-col gap-2
PropDefaultType
locale"en-US"string | undefined

The locale (BCP 47 language tag) to use when formatting the date.

translationsIntlTranslations | undefined

The localized messages to use.

idsPartial<{ root: string; label: (index: number) => string; table: (id: string) => string; tableHeader: (id: string) => string; tableBody: (id: string) => string; tableRow: (id: string) => string; ... 11 more ...; positioner: string; }> | undefined

The ids of the elements in the date picker. Useful for composition.

namestring | undefined

The `name` attribute of the input element.

timeZone"UTC"string | undefined

The time zone to use

disabledboolean | undefined

Whether the calendar is disabled.

readOnlyboolean | undefined

Whether the calendar is read-only.

outsideDaySelectablefalseboolean | undefined

Whether day outside the visible range can be selected.

minDateValue | undefined

The minimum date that can be selected.

maxDateValue | undefined

The maximum date that can be selected.

closeOnSelecttrueboolean | undefined

Whether the calendar should close after the date selection is complete. This is ignored when the selection mode is `multiple`.

valueDateValue[] | undefined

The controlled selected date(s).

defaultValueDateValue[] | undefined

The initial selected date(s) when rendered. Use when you don't need to control the selected date(s) of the date picker.

focusedValueDateValue | undefined

The controlled focused date.

defaultFocusedValueDateValue | undefined

The initial focused date when rendered. Use when you don't need to control the focused date of the date picker.

numOfMonthsnumber | undefined

The number of months to display.

startOfWeeknumber | undefined

The first day of the week. `0` - Sunday `1` - Monday `2` - Tuesday `3` - Wednesday `4` - Thursday `5` - Friday `6` - Saturday

fixedWeeksboolean | undefined

Whether the calendar should have a fixed number of weeks. This renders the calendar with 6 weeks instead of 5 or 6.

onValueChange((details: ValueChangeDetails) => void) | undefined

Function called when the value changes.

onFocusChange((details: FocusChangeDetails) => void) | undefined

Function called when the focused date changes.

onViewChange((details: ViewChangeDetails) => void) | undefined

Function called when the view changes.

onOpenChange((details: OpenChangeDetails) => void) | undefined

Function called when the calendar opens or closes.

isDateUnavailable((date: DateValue, locale: string) => boolean) | undefined

Returns whether a date of the calendar is available.

selectionMode"single"SelectionMode | undefined

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

format((date: DateValue, details: LocaleDetails) => string) | undefined

The format of the date to display in the input.

parse((value: string, details: LocaleDetails) => DateValue | undefined) | undefined

Function to parse the date from the input back to a DateValue.

placeholderstring | undefined

The placeholder text to display in the input.

viewDateView | undefined

The view of the calendar

defaultView"day"DateView | undefined

The default view of the calendar

minView"day"DateView | undefined

The minimum view of the calendar

maxView"year"DateView | undefined

The maximum view of the calendar

positioningPositioningOptions | undefined

The user provided options used to position the date picker content

openboolean | undefined

The controlled open state of the date picker

defaultOpenboolean | undefined

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.

inlineboolean | undefined

Whether to render the date picker inline

dir"ltr""ltr" | "rtl" | undefined

The document's text/writing direction.

getRootNode(() => ShadowRoot | Node | Document) | undefined

A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Provider

PropDefaultType
valueDatePickerApi<PropTypes>

element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Context

PropDefaultType
children(datePicker: DatePickerApi<PropTypes>) => ReactNode

Label

txt
label-text
PropDefaultType
element((attributes: HTMLAttributes<"label">) => Element) | undefined

Render the element yourself

Control

txt
relative flex flex-col gap-2
PropDefaultType
element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

PresetTrigger

PropDefaultType
valuePresetTriggerValue

element((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

Input

txt
input
PropDefaultType
indexnumber | undefined

The index of the input to focus.

fixOnBlurtrueboolean | undefined

Whether to fix the input value on blur.

element((attributes: HTMLAttributes<"input">) => Element) | undefined

Render the element yourself

Trigger

txt
btn-icon btn-icon-sm preset-tonal absolute end-1.5 top-[calc(var(--spacing)*1.25)]
PropDefaultType
element((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

Positioner

PropDefaultType
element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Content

txt
card bg-surface-50-950 border border-surface-200-800 p-2 flex flex-col gap-2
PropDefaultType
element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

YearSelect

txt
select
PropDefaultType
element((attributes: HTMLAttributes<"select">) => Element) | undefined

Render the element yourself

MonthSelect

txt
select
PropDefaultType
element((attributes: HTMLAttributes<"select">) => Element) | undefined

Render the element yourself

View

txt
flex flex-col gap-2
PropDefaultType
viewDateView | undefined

element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

ViewControl

txt
flex gap-2 justify-between
PropDefaultType
element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

PrevTrigger

txt
btn-icon hover:preset-tonal
PropDefaultType
element((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

ViewTrigger

txt
btn hover:preset-tonal
PropDefaultType
element((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

RangeText

PropDefaultType
element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

NextTrigger

txt
btn-icon hover:preset-tonal
PropDefaultType
element((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

Table

txt
border-separate border-spacing-2
PropDefaultType
element((attributes: HTMLAttributes<"table">) => Element) | undefined

Render the element yourself

TableHead

PropDefaultType
element((attributes: HTMLAttributes<"thead">) => Element) | undefined

Render the element yourself

TableRow

PropDefaultType
element((attributes: HTMLAttributes<"tr">) => Element) | undefined

Render the element yourself

TableHeader

txt
size-10
PropDefaultType
element((attributes: HTMLAttributes<"th">) => Element) | undefined

Render the element yourself

TableBody

PropDefaultType
element((attributes: HTMLAttributes<"tbody">) => Element) | undefined

Render the element yourself

TableCell

txt
size-10
PropDefaultType
disabledboolean | undefined

valuenumber | DateValue

columnsnumber | undefined

visibleRangeVisibleRange | undefined

element((attributes: HTMLAttributes<"td">) => Element) | undefined

Render the element yourself

TableCellTrigger

txt
size-full btn p-0 hover:preset-tonal cursor-pointer data-focus-visible:outline-2 data-focus-visible:outline-offset-1 data-focus-visible:outline-surface-950-50 data-selected:preset-filled data-in-range:preset-filled data-today:underline data-today:underline-offset-4 data-disabled:pointer-events-none data-disabled:opacity-50
PropDefaultType
element((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

View page on GitHub