DateRangePicker

Tier: ownUnstable

ImportCopy Anchor Link

import { DateRangePicker } from '@nizivo/react/unstable/date-range-picker';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/button.css and @nizivo/react/css/popover.css and @nizivo/react/css/select.css
import '@nizivo/react/css/date-range-picker.css';

UnstableCopy Anchor Link

It ships at @nizivo/react/unstable/date-range-picker, outside the semver promise, because the design has not drawn an unavailable day or a comparison with the previous period yet. Its props may change in a minor release.

Static or interactiveCopy Anchor Link

Client. It is React Aria's RangeCalendar inside the Popover. The server renders the trigger, with the applied range as its text, and the hidden form input; the popover, the calendar and anything that depends on today's date render only after hydration, when it opens. How to choose.

ValueCopy Anchor Link

value and defaultValue are { start, end }, ISO plain dates ('2026-10-01'), both ends included, or null. Nothing is applied until Apply: choosing a preset or two days only changes what the popover shows, and Cancel, Escape or a press outside keep the old range. onValueChange then gets the range and { reason: 'preset' } or { reason: 'calendar' }. With name, the form gets one field whose value is the ISO interval 2026-10-01/2026-10-07.

timeZone is required: the presets and the today mark count from today in it. min and max limit the days that can be picked.

PresetsCopy Anchor Link

presets lists them in order: today, yesterday, last-7-days, last-30-days, this-quarter, year-to-date (all six by default; [] for none). Each ends today. A chosen preset is shown pressed until a day is picked.

Reading the rangeCopy Anchor Link

The trigger and the footer read the range as labels.range, '{start} – {end}' by default, each end formatted on its own in locale ("Oct 1 – Oct 7, 2026"; the start drops the year when both share it), never with Intl.DateTimeFormat.formatRange, whose spacing differs between browsers. Inside a Field, the trigger is named by its value and the label, as Select's is, and a press on the label focuses it without opening the popover.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { DateRangePicker } from '@nizivo/react/unstable/date-range-picker';

export function DateRangePickerExample(): JSX.Element {
  return (
    <Field label="Report period">
      <DateRangePicker
        name="period"
        timeZone="UTC"
        defaultValue={{ start: '2026-10-01', end: '2026-10-07' }}
      />
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { DateRangePicker } from '@nizivo/react/unstable/date-range-picker';

export function DateRangePickerEmptyExample(): JSX.Element {
  return (
    <Field label="Delivery window">
      <DateRangePicker timeZone="Europe/Berlin" presets={[]} />
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { DateRangePicker } from '@nizivo/react/unstable/date-range-picker';

export function DateRangePickerStatesExample(): JSX.Element {
  const range = { start: '2026-09-28', end: '2026-10-04' };
  return (
    <div style={{ display: 'grid', gap: 16, justifyItems: 'start' }}>
      <DateRangePicker aria-label="Period" timeZone="UTC" size="sm" defaultValue={range} />
      <DateRangePicker aria-label="Period" timeZone="UTC" size="lg" defaultValue={range} />
      <Field label="Campaign dates" error="Pick dates after the campaign was created.">
        <DateRangePicker timeZone="UTC" defaultValue={range} />
      </Field>
      <Field label="Archived period" disabled>
        <DateRangePicker timeZone="UTC" defaultValue={range} />
      </Field>
    </div>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

DateRange type

import type { DateRange } from '@nizivo/react/unstable/date-range-picker'

A range of ISO plain dates ('2026-10-01'), both ends included (§16.3).

Name	Type	Default	Description
endrequired	string	–
startrequired	string	–

DateRangePickerDayState type

import type { DateRangePickerDayState } from '@nizivo/react/unstable/date-range-picker'

A day cell's state, for its classes and data attributes.

Name	Type	Default	Description
daterequired	string	–	The cell's ISO date.
disabledrequired	boolean	–
focusVisiblerequired	boolean	–
hoveredrequired	boolean	–
outsideMonthrequired	boolean	–
pressedrequired	boolean	–
rangeEndrequired	boolean	–
rangeStartrequired	boolean	–
selectedrequired	boolean	–

DateRangePickerLabels type

import type { DateRangePickerLabels } from '@nizivo/react/unstable/date-range-picker'

DateRangePicker's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
applyrequired	string	'Apply'	The footer's button that keeps the new one.
cancelrequired	string	'Cancel'	The footer's button that keeps the old range.
last30Daysrequired	string	'Last 30 days'
last7Daysrequired	string	'Last 7 days'
placeholderrequired	string	'Select dates'	The trigger's text with no range.
presetsrequired	string	'Presets'	The presets list's name.
rangerequired	string	'{start} – {end}'	How a range reads, in the trigger and the footer.
thisQuarterrequired	string	'This quarter'
todayrequired	string	'Today'
yearToDaterequired	string	'Year to date'
yesterdayrequired	string	'Yesterday'

DateRangePickerNavState type

import type { DateRangePickerNavState } from '@nizivo/react/unstable/date-range-picker'

Name	Type	Default	Description
disabledrequired	boolean	–
focusVisiblerequired	boolean	–
hoveredrequired	boolean	–
pressedrequired	boolean	–

DateRangePickerProps type

import type { DateRangePickerProps } from '@nizivo/react/unstable/date-range-picker'

The props of DateRangePicker, listed above.

DateRangePickerState type

import type { DateRangePickerState } from '@nizivo/react/unstable/date-range-picker'

Name	Type	Default	Description
disabledrequired	boolean	–
filledrequired	boolean	–	A range is applied.
invalidrequired	boolean	–
openrequired	boolean	–
sizerequired	ControlSize "sm" | "md" | "lg"	–

DateRangePickerValueReason type

import type { DateRangePickerValueReason } from '@nizivo/react/unstable/date-range-picker'

'preset', 'calendar': how the applied range was chosen; 'clear' is not used yet.

type DateRangePickerValueReason = "preset" | "calendar"

DateRangePreset type

import type { DateRangePreset } from '@nizivo/react/unstable/date-range-picker'

A preset's key. today and the others are counted in timeZone.

type DateRangePreset = "today" | "yesterday" | "last-7-days" | "last-30-days" | "this-quarter" | "year-to-date"

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-date-range-picker-body, .nz-date-range-picker-calendar, .nz-date-range-picker-day, .nz-date-range-picker-footer, .nz-date-range-picker-grid, .nz-date-range-picker-header, .nz-date-range-picker-heading, .nz-date-range-picker-nav, .nz-date-range-picker-nav-icon, .nz-date-range-picker-popup, .nz-date-range-picker-preset, .nz-date-range-picker-presets, .nz-date-range-picker-range, .nz-date-range-picker-weekday, .nz-popover-content, .nz-popover-popup.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• date-range-picker-day: draws the focus outline itself on keyboard focus.
• date-range-picker-nav: draws the focus outline itself on keyboard focus.
• date-range-picker-preset: draws the focus outline itself on keyboard focus.
• date-range-picker-trigger: draws the focus outline itself on keyboard focus.

KeyboardCopy Anchor Link

Source: React Aria Components 1.22.1 RangeCalendar (_engines/react-aria/date-range-picker.client.tsx) inside the Popover. The browser lane (test/browser/date-range-picker.spec.tsx) checks hydration, the trigger's name, opening on the applied month, presets, Apply, Cancel, Escape, two days by keyboard, the time zone's today and the form's value.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 746:267
• Ghost masters: none