Date range picker

• Type: Component (inputs)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/date-range-picker
• Markdown: https://ui.xzero.co.uk/components/date-range-picker/markdown
• Registry item: https://mcp.xzero.co.uk/r/date-range-picker.json
• Source file: registry/components/date-range-picker/date-range-picker.tsx
• Dependencies: motion, lucide-react
• Keywords: inputs, new, react date range picker, date range, calendar range selection, analytics date filter, start and end date, date presets, booking date picker

When to use

• Analytics and reporting filters that need presets like Last 7 days or This quarter.
• Booking or leave requests where a start and end day are picked together.
• Toolbars where the picker must stay compact until opened.

When not to use

• Use date-picker for a single date.
• Use calendar when the month should stay visible on the page.
• Use time-picker when the user chooses a time of day rather than days.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/date-range-picker

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

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

export function ReportRange() {
  const [range, setRange] = useState<DateRange | null>(null);
  return (
    <DateRangePicker
      label="Report period"
      value={range}
      onChange={setRange}
      weekStartsOn={1}
      maxDate={new Date()}
    />
  );
}

API reference

DateRangePicker

A trigger that grows into a panel with one or two months and a preset rail, then shrinks back with the applied range.

Prop	Type	Default	Description
value	DateRange | null	–	Controlled value, { start, end } as inclusive whole days. Pass null for no selection.
defaultValue	DateRange | null	null	Uncontrolled starting value.
onChange	(range: DateRange) => void	–	Called with the range on Apply.
label	string	"Date range"	Accessible name of the trigger and the dialog.
placeholder	string	"Select dates"	Trigger text with no selection.
presets	DateRangePreset[]	defaultDateRangePresets	Shortcuts: { label, range: (today) => DateRange }. Defaults to Today through Year to date.
minDate	Date	–	Earliest selectable day.
maxDate	Date	–	Latest selectable day.
weekStartsOn	0 | 1	0	0 is Sunday, 1 is Monday.
locale	string	"en-US"	Locale for Intl.DateTimeFormat labels and month titles.
months	"auto" | 1 | 2	"auto"	Force one or two months. auto shows two when the boundary is at least 712px wide.
boundary	() => HTMLElement | null	–	Element the panel should stay inside. Defaults to the viewport.
className	string	–	Extra class on the root.

useToday

Hook returning the viewer's local date, or undefined during server render and hydration. Updates at local midnight and when the tab becomes visible.

No props.

Keyboard interactions

Keys	Action
Enter / Space	Opens the panel from the trigger; picks a start or end day in the grid.
Arrow keys	Move by day or week in the grid, extending the range preview once a start is picked.
Home / End	Jump to the start or end of the week.
PageUp / PageDown	Move by month; add Shift to move by year.
ArrowUp / ArrowDown	Move between presets in the rail; ArrowLeft and ArrowRight in the compact row.
Escape	Closes without applying and returns focus to the trigger.

Accessibility

• The trigger has aria-haspopup="dialog", aria-expanded, and a label that includes the current range.
• Each month is a role="grid" labelled by its title, with columnheaders and gridcells using aria-selected for days in range and aria-current="date" for today.
• Days have full date labels and a roving tabindex; months that are leaving turn inert so focus only finds the current set.
• A polite live region announces the start day, then the range and its length.

Motion

• The trigger surface grows into the panel on a physical spring and shrinks back on Apply while the formatted label flies into the trigger with a shared layoutId.
• The range highlight is one bar per week that stretches as you hover, and the two ends glide between days.
• Months slide in the direction of travel, and label words roll up or down with time's direction.
• Reduced motion jumps the surface size, drops the shared layout and slide, and uses short opacity fades.

Responsive behavior

• months="auto" shows two months beside a vertical preset rail when the boundary is at least 712px wide, otherwise one month under a scrolling preset row.
• In compact mode the panel width is min(352px, available) and day cells size between 32 and 42px to fit.
• The panel shifts horizontally to stay 8px inside the boundary, and recomputes on window resize.

Performance

• ResizeObservers on the trigger and panel feed the size springs; updates are batched through a microtask.
• Each week's highlight and each end is a motion value animation, so hovering does not re-render the grid beyond the range change.
• Intl.DateTimeFormat instances are memoized per locale.

Notes for AI

• Use when a start and end date are chosen together: report filters, analytics periods, bookings.
• Selection is draft until Apply; onChange fires only on Apply. Cancel, Escape, or an outside click discards the draft.
• Pass custom presets as { label, range: today => ({ start, end }) }; today is the viewer's local date.
• The trigger is disabled until hydration because today is unknown on the server.
• For a single date use date-picker; for an always-visible month use calendar.

Related

• Date picker: Choose a date without losing context.
• Calendar: Browse dates in a clear, compact month view.
• Time picker: Choose a time with sensible keyboard behavior.
• Filter toolbar: Keep collection filters close and easy to reset.

Also in pickers

• Color picker: A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.
• Emoji picker: A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid.

Guidance for AI tools

Date range picker: A range picker that grows from its trigger into two months with presets and a stretching range highlight. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt