Date Range Picker

A start and end date, with presets beside a calendar.

Source
$npx @dinachi/cli@latest add date-range-picker

No range yet

presentation
presets
noFuture
disabled

Usage

import { useState } from "react"
import { type DateRange } from "@/components/ui/calendar"
import { DateRangePicker } from "@/components/ui/date-range-picker"

export function Period() {
  const [range, setRange] = useState<DateRange>({ from: null, to: null })
  return <DateRangePicker aria-label="Period" value={range} onValueChange={setRange} max={new Date()} />
}

Examples

A report period, nothing after today.
import { useState } from 'react';
import { addDays, startOfDay, type DateRange } from '@/components/ui/calendar';
import { DateRangePicker } from '@/components/ui/date-range-picker';

export function Example() {
  const today = startOfDay(new Date());
  const [range, setRange] = useState<DateRange>({ from: addDays(today, -6), to: today });
  return <DateRangePicker aria-label="Period" value={range} onValueChange={setRange} max={today} />;
}

Notes

Server rendering

Pass today when the page renders on a server, so the server and the browser agree on which day it is.

Presets and Custom

Picking on the calendar switches the preset to Custom. A preset range names itself on the trigger with its dates beside it; a custom one shows its dates. Pressing Custom clears the range to start again.

Apply and Cancel

The range is a draft until Apply, which stays off until the range has an end. Cancel, Esc and a click outside all leave the applied range as it was. While you pick the end, the footer counts the days to the one under the pointer. A range set from outside that runs across a blocked day marks the trigger invalid, and the footer says which day.

API

value
agent
DateRange
Controlled { from, to }.
defaultValueDateRange
Starting value when uncontrolled.
onValueChange
agent
(value, details) => void
Runs on Apply, not while a range is being picked. details.cancel() refuses it.
presets
agent
{ label: string; value: DateRange }[]
Defaults to pastPresets(today): today, yesterday, the last 7 and 30 days, this month and last month. Pass [] for none. Presets outside the bounds are dropped; one that runs across a blocked day shows disabled, with the reason.
formatRange({ from, to }) => string = 11 to 17 Nov 2026
How a range reads on the trigger and in the footer.
formatLength({ from, to }) => string = 3 days
How long a range reads in the footer. Return nights for a stay.
allowDisabledEnd
agent
boolean = false
Lets a range end on the first disabled day after its start, as a stay checks out on a booked night.
onDraftChange(draft, details) => void
Runs as the range being picked changes, before Apply. details.reason is range-blocked when a press past a blocked day restarted it.
open, defaultOpen, onOpenChangeboolean, boolean, (open) => void
Controls whether the picker is open.
min
agent
Date
The earliest day.
max
agent
Date
The latest day. Set it to today for reports.
isDateDisabled
agent
(date: Date) => boolean
Blocks single days. A range can't run across one.
presentation"auto" | "popover" | "drawer" = "auto"
A popover from 768px up and a drawer below, unless one is named.
labelstring = "Date range"
Names the popover and titles the drawer.
placeholderstring = "Pick dates"
The trigger's text with no range.
namestring
Submits the range as YYYY-MM-DD/YYYY-MM-DD.
requiredboolean = false
Fails form validation without a range, and points the browser at the trigger.
disabled
agent
boolean = false
Blocks people and agents.
layout, numberOfMonths, captionLayout, renderDay, dayClassName, describeDay, weekNumbers, locale, weekStartsOn, dir, todayAs Calendar
Passed to the calendar.

Agent

Inside an AgentProvider, it appears in agent.snapshot() as date.

Reads

label

The trigger's aria-label.

value

[from, to] as YYYY-MM-DD, or absent when empty.

items

The preset labels, any of which setValue accepts.

multiple

Always true: the value is a list.

invalid

True when the range set from outside runs across a blocked day.

Actions

setValue("Last 7 days")

Applies a preset by its label.

setValue(["2026-11-02", "2026-11-08"])

Applies two dates. "2 nov to 8 nov" works too.

clear()

Empties the range.

An agent's change runs through onValueChange like anyone's. isAgentChange(details) is true for it; details.cancel() refuses it. A range that ends before it starts, falls outside min and max, or runs across a blocked day is refused with the reason.

await agent.act({
  steps: [{ ref: "Period", action: "setValue", args: ["Last 30 days"] }],
})

Accessibility

  • The trigger's name holds the range, after its label when one is given.
  • Presets are toggle buttons; the active one has aria-pressed.
  • The footer is a live region, so the range and day count are announced as they change.