Browse docs

DateRangePicker

DateRangePicker is a form-connected start/end date field: a read-only trigger paired with a dual-month range calendar popover. Click a start date, then an end date — a hovered preview band tracks the in-progress range. It integrates with DashForm and RBAC automatically.

The stored value is a { start, end } pair of plain ISO calendar dates (YYYY-MM-DD); either side may be null. No time, no time zone.

The range state machine — start, end, swap, hover preview, dual-month — lives in the headless useDateRange hook from @dashforge/calendar-core, shared with the MUI @dashforge/ui skin.

Quick Start

tsx

import { DashForm } from '@dashforge/forms';
import { DateRangePicker } from '@dashforge/tw';

<DashForm onSubmit={(data) => console.log(data)}>
  <DateRangePicker name="bookingPeriod" label="Booking period" />
</DashForm>

The committed value is an object:

{ start: '2026-05-12', end: '2026-05-18' }

Examples

A basic field — click the trigger, pick a start date, then an end date.

Booking period

import { DateRangePicker } from '@dashforge/tw';

<DateRangePicker name="bookingPeriod" label="Booking period" />

Constrained range

minDate / maxDate bound the selectable dates; disabledDates and the isDateDisabled predicate block specific days.

Stay

import { DateRangePicker } from '@dashforge/tw';

<DateRangePicker
  name="stay"
  label="Stay"
  minDate="2026-05-01"
  maxDate="2026-06-30"
  defaultValue={{ start: '2026-05-12', end: '2026-05-18' }}
/>

Theme defaults

Configure <DateRangePicker> defaults application-wide.

tsx

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    DateRangePicker: {
      defaults: { layout: 'stacked', weekStartDay: 1, locale: 'en-GB', fullWidth: false },
    },
  },
});

Configurable axes (DateRangePickerVariantProps):

Axis	Type	Notes
`layout`	`'stacked' \| 'inline'`	Label position (above vs left of the trigger).
`weekStartDay`	`WeekDay` (`0 \| 1 \| … \| 6`)	First-column weekday of the popover calendar.
`locale`	`string`	BCP-47 locale for the calendar + display format.
`fullWidth`	`boolean`	Stretch root + trigger to container width.

Non-visual axes (name, rules, label, helperText, placeholder, required, error, disabled, value, defaultValue, onChange, minDate, maxDate, disabledDates, isDateDisabled, access, visibleWhen) are per-instance.

Precedence chain (lowest → highest):

Built-in defaults (layout: 'stacked', weekStartDay: 0, locale: 'en-US', fullWidth: false).
theme.components.DateRangePicker.defaults (application-wide).
Instance prop — wins over theme.
sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.DateRangePicker.defaults autocompletes to the four axes above.

Reactivity: useComponentDefaults('DateRangePicker') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Prop	Type	Default	Description
`name`	`string`	—	Field name — the bridge registration key. Required.
`access`	`AccessRequirement`	—	RBAC access requirement.
`defaultValue`	`DateRange`	—	Uncontrolled initial value.
`disabled`	`boolean`	—	Disables the field.
`disabledDates`	`readonly ISODate[]`	—	Explicit list of disabled dates.
`error`	`boolean`	—	Explicit error state (overrides the bridge's auto error).
`fullWidth`	`boolean`	—	Stretches the field to its container width.
`helperText`	`ReactNode`	—	Helper text below the control (overrides a bridge error message).
`isDateDisabled`	`(date: ISODate) => boolean`	—	Predicate marking arbitrary dates disabled.
`label`	`ReactNode`	—	Field label.
`layout`	`'stacked' \| 'inline'`	—	Label/control layout.
`locale`	`string`	—	BCP-47 locale for the calendar and the display format.
`maxDate`	`ISODate`	—	Latest selectable date (inclusive).
`minDate`	`ISODate`	—	Earliest selectable date (inclusive).
`onChange`	`(value: DateRange) => void`	—	Fired with the new range (partial on the first click, complete on the second).
`placeholder`	`string`	—	Placeholder shown when no range is selected.
`required`	`boolean`	—	Marks the field required (adds the label asterisk).
`rules`	`unknown`	—	Validation rules forwarded to the form bridge.
`slotProps`	`DateRangePickerSlotProps`	—	Per-slot `className` overrides.
`sx`	`string`	—	Root-level Tailwind class override.
`testId`	`string`	—	Test id applied to the field root.
`value`	`DateRange`	—	Controlled value — a `{ start, end }` pair.
`visibleWhen`	`(engine: Engine) => boolean`	—	Reactive visibility predicate evaluated against the form engine.
`weekStartDay`	`WeekDay`	—	Weekday of the calendar's first column (`0` = Sunday).

Slots & slotProps

<DateRangePicker> is a compound component with 6 named slots. Each slot accepts a { className?: string } override via slotProps:

Slot	Purpose
`root`	Outer wrapper (label + trigger + helper/error).
`label`	The `<label>` element.
`requiredMark`	The red `*` when `required`.
`trigger`	The read-only `<button>` that opens the dual-month popover.
`helperText`	Helper text line, when not in error state.
`errorText`	Helper text line, when in error state.

Use sx for a root-level class override; use slotProps for a specific inner region. The popover dual-calendar itself inherits theme.components.Calendar.defaults for its inner day-cell surface.

Notes

{ start, end } storage. The bridge value is an object of two ISO YYYY-MM-DD dates; either side is null until picked. onChange fires twice — once with { start, end: null } after the first click, then with the complete pair after the second.
Dual-month. The popover shows two consecutive months side by side so a cross-month range is selectable without paging.

Capabilities

Controlled

tsx

<DateRangePicker value={range} onChange={(r) => setRange(r)} label="Period" />

React Hook Form ready

Inside DashForm the field registers automatically — validation, error gating, and touch tracking flow through the bridge.

RBAC access control

tsx

<DateRangePicker
  name="reportWindow"
  label="Report window"
  access={{ resource: 'report', action: 'read', onUnauthorized: 'readonly' }}
/>