Browse docs

DateRangePicker

DateRangePicker is a form-connected start/end date field: a read-only text input paired with a dual-month range calendar popup. Click a start date, then an end date — a hovered preview band tracks the in-progress range. It integrates with DashForm, RBAC, and the Dashforge field layout 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.

Quick Start

tsx

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

<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 icon, pick a start date, then an end date.

Booking period

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

Constrained range

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

Stay

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

API

Prop	Type	Default	Description
`name`	`string`	—	Field name — the bridge registration key. Required.
`label`	`ReactNode`	—	Field label.
`helperText`	`ReactNode`	—	Hint text below the control.
`rules`	`RegisterOptions`	—	Validation rules forwarded to the form bridge.
`required`	`boolean`	`false`	Adds the label asterisk.
`error`	`boolean`	—	Explicit error state (overrides the bridge's auto error).
`disabled`	`boolean`	`false`	Disables the field.
`placeholder`	`string`	—	Shown when no range is selected.
`layout`	`'stacked' \| 'inline' \| 'floating'`	`'stacked'`	Label / control layout. `floating` is downgraded to `stacked`.
`value`	`{ start, end }`	—	Controlled value.
`defaultValue`	`{ start, end }`	—	Uncontrolled initial value.
`onChange`	`(value: { start, end }) => void`	—	Fired on each change — partial after the first click, complete after the second.
`minDate` / `maxDate`	`ISODate`	—	Selectable bounds (inclusive).
`disabledDates`	`ISODate[]`	—	Explicit list of disabled dates.
`isDateDisabled`	`(date: ISODate) => boolean`	—	Predicate disabling arbitrary dates.
`weekStartDay`	`WeekDay`	`0`	First-column weekday of the popup calendar.
`locale`	`string`	`'en-US'`	BCP-47 locale for the calendar + display format.
`visibleWhen`	`(engine: Engine) => boolean`	—	Reactive visibility predicate.
`access`	`AccessRequirement`	—	RBAC access requirement.
`fullWidth`	`boolean`	`false`	Stretches the field to its container width.
`testId`	`string`	—	Test id applied to the field root.

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 popup shows two consecutive months side by side so a cross-month range is selectable without paging.
Read-only input. The text input is set only via the calendar popup, so the stored range is always valid.

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' }}
/>