Date Picker
One control for both jobs: a calendar period or a custom range, behind a mode switch. It owns the switch and the popover only — the two panels are a DatePicker.Period.Root and a DatePicker.Range.Root mounted inside it, both editing AssetProvider's single dateFrom/dateTo range. That range is what every date-driven component reports on, so a choice here moves the whole page. A third, pinned-only day mode picks one day on the same calendar: the end of the provider range, which a pick collapses onto that day.
Preview
Loading preview…
Anatomy
Import the primitive and compose the parts you need.
<DatePicker.Root> <DatePicker.Anchor> <DatePicker.Trigger><DatePicker.Value /></DatePicker.Trigger> </DatePicker.Anchor> <DatePicker.Portal> <DatePicker.Content> <DatePicker.ModeSwitch> <DatePicker.ModeOption mode="period" /> <DatePicker.ModeOption mode="range" /> </DatePicker.ModeSwitch> <DatePicker.PeriodMode> <DatePicker.Period.Root>{/* period panel */}</DatePicker.Period.Root> </DatePicker.PeriodMode> <DatePicker.RangeMode> <DatePicker.Range.Root> <DatePicker.Range.Calendar /> </DatePicker.Range.Root> </DatePicker.RangeMode> <DatePicker.DayMode> <DatePicker.DayCalendar /> </DatePicker.DayMode> </DatePicker.Content> </DatePicker.Portal></DatePicker.Root>API reference
Root props
| Prop | Type | Default | Description |
|---|---|---|---|
mode | "period" | "range" | "day" | — | Locks the picker to a single panel and hides the mode switch. Omitted, the period and range panels are offered. Mount "period" on a surface built around period-over-period comparisons, so the range always names a month, quarter or year. "day" is never behind the switch: it binds to the provider as a one-day range, unless value and onValueChange are given. |
value | CalendarDateString | — | Day mode only, with onValueChange: the selected day as YYYY-MM-DD, or "" for none. Makes the picker a controlled field that never touches the provider range. |
onValueChange | (value: CalendarDateString) => void | — | Day mode only, with value: receives the picked day as YYYY-MM-DD. |
min | CalendarDateString | — | Day mode's earliest selectable day, inclusive. The calendar disables the days outside the bounds; the period and range panels take their bounds on their own roots. |
max | CalendarDateString | — | Day mode's latest selectable day, inclusive. |
disabled | boolean | — | Disables the trigger, the mode switch and the day calendar. |
Parts
Popover
| Part | Description |
|---|---|
DatePicker.ValueasChild?, format? | Formats the provider range: "All 2026", "Q3 2026", "Mar 2026", or "1 Jan – 31 Mar 26" when it matches no calendar period. |
DatePicker.AnchorasChild? | Anchors the popover to the trigger. |
DatePicker.TriggerasChild? | Opens the popover on the mode matching the current range. |
DatePicker.Portal | Renders content outside clipping ancestors. |
DatePicker.ContentasChild? | Modal popover content, carrying the active mode as `data-mode`. |
Mode switch
| Part | Description |
|---|---|
DatePicker.ModeSwitchasChild? | Accessible group wrapping the two mode options. Renders nothing while Root's mode prop locks the panel. |
DatePicker.ModeOptionmode, asChild? | Switches to "period" or "range", defaulting to the labels Period and Custom. Reflects the active mode as aria-pressed and data-active. |
DatePicker.PeriodMode | Renders its children only while the period panel is active. |
DatePicker.RangeMode | Renders its children only while the custom-range panel is active. |
DatePicker.DayMode | Renders its children only while Root is pinned to day mode. |
Day mode
| Part | Description |
|---|---|
DatePicker.DayValueasChild?, format?, placeholder? | The selected day, "Mar 15, 2026" by default: the end of the provider range when bound to it, the controlled value otherwise. Shows the placeholder, with data-placeholder="true", while a controlled picker has nothing picked. |
DatePicker.DayCalendar…DayPicker props | One-day calendar opening on the selected day's month. A pick sets the provider range to that one day (or hands it to onValueChange) and closes the popover; days outside Root's min and max are disabled. |
Panels
| Part | Description |
|---|---|
DatePicker.Period.* | The period panel compound: Root, Group, YearOption, QuarterOption, MonthOption, PreviousYear, DisplayYear, and NextYear. Root takes min, max, and disabled. |
DatePicker.Range.* | The custom-range panel compound: Root and Calendar. Root takes min, max, and disabled; the calendar picks a range in a three-click cycle. |
Hook
| Part | Description |
|---|---|
DatePicker.useDatePicker() | Returns the active mode, the provider range, its exact period when it has one, day mode's selected day, open state, and the mode, open and selectDay actions. |
Modes
Both panels are views of the same canonical range, so switching modes never writes to the provider. Move from Period to Custom and the calendar opens on the days the chosen period covers; move back and the period grid still shows that period selected.
Every date-driven component under the provider follows the committed range, unless it was detached with its own dateFrom/dateTo props. Cards that compare against a previous period can only do so period-over-period when the range names one, so a surface built around those comparisons should mount the picker with mode="period"; a custom range is compared against the same number of days immediately before it.
Opening lands on the mode that matches what is selected: an exact calendar year, quarter, or month opens on Period, anything else on Custom. A range picked in Custom that happens to be a whole month is an exact period, so the next open shows Period with that month selected. A fixed mode always opens on its own panel instead.
mode="day" only ever comes pinned, for a surface reported as of one day. Without a value it binds to the provider: DayValue shows the end of the range, the day the page reports on, so seed the provider with a dateTo on or before max. The calendar opens on that day's month, and a pick sets the range to that one day through the same provider path the other panels use, so onDateRangeChange receives { start: day, end: day }. Given value and onValueChange it is a controlled field for a form instead, which neither reads nor writes the provider range.
Composition
The nested roots keep their own props: pass min and max to the DatePicker.Period.Root and DatePicker.Range.Root you mount inside PeriodMode and RangeMode, since those bounds belong to the panel that enforces them. Day mode has no nested root, so its bounds go on DatePicker.Root alongside mode, disabled and the optional value / onValueChange; the DayCalendar inside DayMode reads them from there.