DateRangeField
Form control for an optional date range selected through a calendar.
Component behavior
DateRangeField selects an optional date range through a calendar popover. The trigger is a button; typed date entry is not available. Use null for an empty range.
- A start and end date within one form field.
- Optional date ranges represented by
null. - Arbitrary date ranges without required presets.
DateRangePicker: the range is a required dashboard filter with presets.
DatePicker: one date or typed date entry is required.
MiniCalendar: the grid remains open and the application manages range selection.
Props
DateRange contains start and end dates at local midnight. Both boundary days are included. value and onChange are required; there is no defaultValue. The first selected date is internal state. The second selection calls onChange with a complete range.
| Prop | Type | Default | Description |
|---|---|---|---|
value | DateRange | null | — | Current range. null renders the placeholder and hides the clear button. |
onChange | (range: DateRange | null) => void | — | Called with a complete range on the second day click, or with null when the clear button is pressed. Never called with a partial range. |
placeholder | string | "Pick a range" | Trigger text when value is null. |
disabled | boolean | — | Disables the trigger and hides the clear button. |
align | "start" | "end" | "start" | Popover alignment relative to the trigger: bottom-start or bottom-end. |
size | "sm" | "md" | "md" | Control height. |
className | string | — | Targets the trigger button. |
Examples
Empty to filled
The calendar requests a start date, then an end date. Selected dates are sorted before onChange is called. Selecting the same day twice produces a one-day range.
The trigger label
The label comes from the exported formatDateRange and is not configurable; there is no format prop. It collapses a shared year (Mar 3 – Mar 14, 2026) and spells both out when the range crosses one (Dec 28, 2025 – Jan 4, 2026).
In a form
Wrap the control in a Field for a label and hint. Validate required ranges in application code; the component accepts null.
Compact, right-aligned
size="sm" matches the other toolbar controls, and align="end" anchors the popover to the trigger’s right edge, which avoids overflow when the field is at the right of a row.
import { DateRangeField, formatDateRange } from "@solarius/onset";
import type { DateRangeFieldProps, DateRange } from "@solarius/onset";