DateRangePicker
Choose a date, datetime or time range. Calendar modes use local Date tuples; time-only mode uses string tuples. Use DatePicker for a single value.
Basic usage
Select the start, then the end to commit a complete range and close the panel. Date mode supports reversed selection and orders the result from start to end. Set an initial uncontrolled range with defaultValue.
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DateRangePickerBasic() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="Date range">
<DateRangePicker />
</FormField>
</Form>
);
}
Examples
Controlled value and selection progress
onChange receives the committed range and two formatted strings; clearing returns null and ['', '']. onCalendarChange observes panel-selection drafts and the edited endpoint, not a committed range, and does not cover every text or preset change. Update application state when resetting a controlled field.
import { Button, type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const initialRange: DateRange = [new Date(2026, 9, 5), new Date(2026, 9, 9)];
function formatDate(date: Date | null) {
if (!date) return '-';
return [date.getFullYear(), date.getMonth() + 1, date.getDate()]
.map((part, index) => (index === 0 ? String(part) : String(part).padStart(2, '0')))
.join('-');
}
export function DateRangePickerControlled() {
const [value, setValue] = useState<DateRange | null>(initialRange);
const [committed, setCommitted] = useState('2026-10-05 ~ 2026-10-09');
const [draft, setDraft] = useState('Not adjusted');
return (
<Form
layout="vertical"
onSubmit={(event) => event.preventDefault()}
onReset={() => {
setValue(initialRange);
setCommitted('2026-10-05 ~ 2026-10-09');
setDraft('Not adjusted');
}}
>
<FormField label="Controlled date range">
<DateRangePicker
value={value}
onChange={(next: DateRange | null, texts: readonly [string, string]) => {
setValue(next);
setCommitted(next ? texts.join(' ~ ') : 'Empty');
}}
onCalendarChange={(next, { position }) => {
setDraft(`${position}: ${next.map(formatDate).join(' ~ ')}`);
}}
/>
</FormField>
<Text tone="muted" role="status">
Committed: {committed}
</Text>
<Text tone="muted" role="status">
Latest panel edit: {draft}
</Text>
<Button type="reset">Reset</Button>
</Form>
);
}
Picker modes
Set picker to select years, quarters, months or weeks. Both Date values represent the start of their period. ConfigProvider sets the first weekday with weekStartsOn, defaulting to Monday.
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DateRangePickerModes() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="Year range">
<DateRangePicker picker="year" />
</FormField>
<FormField label="Quarter range">
<DateRangePicker picker="quarter" />
</FormField>
<FormField label="Month range">
<DateRangePicker picker="month" />
</FormField>
<FormField label="Week range">
<DateRangePicker picker="week" />
</FormField>
</Form>
);
}
Date-time ranges
With picker="datetime", choose the start date and time, select Next to edit the end, then OK to commit. The datetime panel requires the end not to precede the start. defaultTime supplies times for newly picked endpoints, not an initial range.
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DateRangePickerDateTime() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="Booking window">
<DateRangePicker picker="datetime" defaultTime={['09:00', '18:00']} minuteStep={15} />
</FormField>
</Form>
);
}
This mode defaults to needConfirm={true} and discards an unconfirmed range on outside clicks. Other calendar modes commit after choosing an end by default; set needConfirm to require confirmation. Escape discards the current edit. Clearing or choosing a valid preset commits directly.
Restrict selectable endpoints
minDate / maxDate include their boundaries. disabledDate receives position to distinguish start and end. This example restricts endpoints to October and excludes Sundays as endpoints; a range may still span a Sunday. Validate whole-range availability in the application if required.
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DisabledDates() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="October delivery window">
<DateRangePicker
defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
minDate={new Date(2026, 9, 1)}
maxDate={new Date(2026, 9, 31)}
disabledDate={(date) => date.getDay() === 0}
/>
</FormField>
</Form>
);
}
Restrictions apply to typing and panel selection without clearing existing values. Datetime bounds compare complete timestamps; disabledTime receives time parts, endpoint position and the current date. inputReadOnly prevents typing, while readOnly prevents changes.
Open endpoints
allowEmpty permits empty endpoints independently. This example uses [false, true] for a required start and optional end, with OpenDateRange imported from the root entry. At least one endpoint must remain non-empty; use null, not [null, null], to clear the whole control.
import { DateRangePicker, Form, FormField, type OpenDateRange, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function OpenEnd() {
const [value, setValue] = useState<OpenDateRange | null>([new Date(2026, 9, 5), null]);
const [texts, setTexts] = useState<readonly [string, string]>(['2026-10-05', '']);
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="Ongoing project period">
<DateRangePicker
allowEmpty={[false, true]}
value={value}
onChange={(next: OpenDateRange | null, dateStrings: readonly [string, string]) => {
setValue(next);
setTexts(dateStrings);
}}
/>
</FormField>
<Text tone="muted" role="status">
Start: {texts[0] || 'Empty'}; end: {texts[1] || 'Empty'}
</Text>
</Form>
);
}
Clear an allowed endpoint with the panel footer action; its callback string is ''. Opening with only a start continues editing the end.
Time range
With picker="time", values and callbacks use ['HH:mm', 'HH:mm'] or null, or HH:mm:ss with showSeconds. use12Hours changes display only; values stay in 24-hour format. minTime / maxTime apply to both endpoints. Time-only mode does not support allowEmpty.
import { DateRangePicker, Form, FormField, Text, type TimeRange } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function DateRangePickerTime() {
const [value, setValue] = useState<TimeRange | null>(['09:00', '18:00']);
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="Working hours">
<DateRangePicker picker="time" value={value} onChange={setValue} />
</FormField>
<Text tone="muted" role="status">
Current value: {value ? value.join(' ~ ') : 'Empty'}
</Text>
</Form>
);
}
Across midnight
By default, the end must not precede the start. Set allowOvernight to allow 22:00 to 06:00 the next day without swapping endpoints. Time mode commits valid changes on dismissal by default; set needConfirm to require explicit confirmation.
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DateRangePickerOvernight() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="Overnight shift">
<DateRangePicker picker="time" allowOvernight defaultValue={['22:00', '06:00']} />
</FormField>
</Form>
);
}
Range shortcuts
presets provides common ranges, previewed on hover or focus. Choosing a valid range commits it immediately and closes the panel. value may be a range or a function returning one synchronously, not a Promise. Functions may run multiple times and must have no side effects.
import { type DateRange, DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';
function recentSevenDays(): DateRange {
const end = new Date();
end.setHours(0, 0, 0, 0);
const start = new Date(end);
start.setDate(start.getDate() - 6);
return [start, end];
}
export function Presets() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="Reporting range">
<DateRangePicker presets={[{ label: 'Recent 7 days', value: recentSevenDays }]} />
</FormField>
</Form>
);
}
A custom format changes display and the string tuple passed to onChange. FormData retains canonical formats joined as start/end. This example displays DD/MM/YYYY and submits a value such as 2026-10-05/2026-10-09; an open end produces 2026-10-05/, and clearing produces an empty string. Resetting an uncontrolled field restores defaultValue.
import { Button, DateRangePicker, Form, FormField, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function DateRangePickerForm() {
const [submitted, setSubmitted] = useState<string | null>(null);
return (
<Form
layout="vertical"
onSubmit={(event) => {
event.preventDefault();
setSubmitted(String(new FormData(event.currentTarget).get('reportingRange') ?? ''));
}}
onReset={() => setSubmitted(null)}
>
<FormField label="Reporting period">
<DateRangePicker
name="reportingRange"
format="DD/MM/YYYY"
defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
/>
</FormField>
<Space>
<Button type="submit">Submit</Button>
<Button type="reset">Reset</Button>
</Space>
<Text tone="muted" role="status">
FormData: {submitted === null ? 'Not submitted' : JSON.stringify(submitted)}
</Text>
</Form>
);
}
For canonical period/datetime formats and custom parse, see DatePicker: display format and form submission. Dates are local calendar values; handle business timezone conversion in the application. See Form for other form configuration.
Paste a complete date range with endpoints separated by ~. Enter commits valid input. Invalid or incomplete input reverts when focus leaves the whole control; Escape discards the edit. See DatePicker: input and confirmation for segmented input.
API
DateRangePicker API
The main table covers calendar and time-only branches, but not every prop applies to both. allowEmpty, format, parse, presets, date bounds and calendar configuration belong to calendar modes; allowOvernight and minTime / maxTime belong to time-only mode.
Native input attributes and aria-* target the input; className / style target the wrapper. See PopupOptions for shared popup configuration.
DateRange
A complete date range uses readonly [Date, Date]. With allowEmpty, use OpenDateRange from the root entry: readonly [Date | null, Date | null]. See DatePreset for preset entries.
TimeRangePickerMode API
Props for picker="time"; TimeRange is readonly [string, string].