For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/date-range-picker.md.

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.

basic.tsx
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.

Committed: 2026-10-05 ~ 2026-10-09Latest panel edit: Not adjusted
controlled.tsx
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.

modes.tsx
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.

datetime.tsx
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.

disabled-dates.tsx
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.

Start: 2026-10-05; end: Empty
open-end.tsx
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.

Current value: 09:00 ~ 18:00
time.tsx
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.

overnight.tsx
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.

presets.tsx
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>
  );
}

Display format and form submission

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.

FormData: Not submitted
form.tsx
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.

PropertyTypeDefaultDescription
picker'year' | 'quarter' | 'month' | 'week' | 'date' | 'datetime' | 'time''date'Select a date, time, date-time, week, month, quarter or year.
valuereadonly [Date, Date] | null | readonly [Date | null, Date | null] | readonly [string, string]—Controlled range: a Date tuple for date modes, with nullable endpoints when allowEmpty is enabled; a 24-hour string tuple for time. The empty range is null.
defaultValuereadonly [Date, Date] | null | readonly [Date | null, Date | null] | readonly [string, string]nullInitial uncontrolled range matching picker, restored on native form reset.
onChange(((value: readonly [Date, Date] | null, dateStrings: readonly [string, string]) => void)) | (((value: readonly [Date | null, Date | null] | null, dateStrings: readonly [string, string]) => void)) | ((value: readonly [string, string] | null) => void)—Called when committing a range: Date and string tuples for date modes, a string tuple for time, null on clear.
onCalendarChange(range: readonly [Date | null, Date | null], info: { position: 'start' | 'end' }) => void—Called for date-panel draft, time and endpoint-clear changes, not a commit; text input and presets do not necessarily call it.
allowEmptyfalse | true | readonly [boolean, boolean]falseExplicitly allow open range endpoints.
size'sm' | 'md' | 'lg''md'Control size
status'error' | 'warning'—Validation appearance
disabledbooleanfalseDisable interaction.
inputReadOnlyboolean—Disable typing while retaining panel selection.
allowClearbooleantrueShow the clear button
minDateDate—Earliest / latest allowed values
maxDateDate—Earliest / latest allowed values
disabledDate(date: Date, position: 'start' | 'end') => boolean—Restrict endpoints, not every date inside the range; position identifies start or end.
minTimestring—Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.
maxTimestring—Latest selectable time, inclusive, as HH:mm or HH:mm:ss.
disabledTime((parts: TimeParts, position: 'start' | 'end', date: Date) => boolean) | ((parts: TimeParts, position: 'start' | 'end') => boolean)—Restrict endpoint times; datetime mode also receives the endpoint Date.
allowOvernightbooleanfalseAllow a time-only range to cross midnight.
needConfirmbooleanpicker === "datetime"Require OK or Enter to commit; discard the draft on blur when enabled.
showSecondsbooleanfalseInclude seconds in date-time ranges; otherwise seconds are zero
use12HoursbooleanfalseDisplay a 12-hour clock with AM/PM options
minuteStepnumber1Minute segment step and column interval, retaining existing off-step values.
secondStepnumber1Second segment step and column interval, retaining existing off-step values.
defaultTimereadonly [string, string]['00:00:00', '23:59:59']Times applied to newly picked start and end dates in datetime mode, as HH:mm[:ss].
formatstring | ((date: Date) => string)—Display format; dates support YYYY, MM, DD, HH, mm, ss and Q.
parse(text: string) => Date | null—Parse entered text; return null on failure.
presetsreadonly DatePreset<readonly [Date | null, Date | null]>[]—Presets; value may be computed on demand.
panelValueDate—Controlled date displayed by the calendar panel.
onPanelChange(date: Date) => void—Called when the displayed calendar period changes.
cellRender(date: Date) => ReactNode—Customize calendar cell content.
openboolean—Control whether the panel is open.
defaultOpenboolean—Initial open state.
onOpenChange(open: boolean) => void—Called when the panel opens or closes
panelVariant'plain' | 'card''plain'Panel appearance; card places the content on an inset surface above a muted canvas.
namestring—Field name in native FormData.
formstring—ID of the associated native form.
requiredbooleanfalseRequire a non-empty value; compound controls validate once.
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—Placement relative to the trigger.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—Custom popup styles.
popupRender(content: React.ReactNode) => React.ReactNode—Wrap or extend popup content; retain the supplied content to preserve interaction.
getPopupContainer() => Element | DocumentFragment—Return a popup container, including a ShadowRoot.
refRef<HTMLInputElement>—Input element reference

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.

PropertyTypeDefaultDescription
0DateRequiredStart, no later than the end
1DateRequiredEnd

TimeRangePickerMode API

Props for picker="time"; TimeRange is readonly [string, string].

PropertyTypeDefaultDescription
picker'time'RequiredTime-only range mode; pass time.
valuereadonly [string, string] | null—Controlled tuple of 24-hour strings; null represents an empty range.
defaultValuereadonly [string, string] | nullnullInitial value; uncontrolled fields support native form reset.
onChange(value: readonly [string, string] | null) => void—Return a tuple of 24-hour strings on commit, or null on clear.
size'sm' | 'md' | 'lg''md'Presentation size.
status'error' | 'warning'—Show an error or warning appearance without performing validation.
allowClearbooleantrueShow a clear action.
inputReadOnlyboolean—Disable typing while retaining panel selection.
minTimestring—Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.
maxTimestring—Latest selectable time, inclusive, as HH:mm or HH:mm:ss.
disabledTime(parts: TimeParts, position: 'start' | 'end') => boolean—Disable times; typing and panel selection use the same rules.
allowOvernightbooleanfalseAllow a time-only range to cross midnight.
needConfirmbooleanfalseRequire OK or Enter to commit; discard the draft on blur when enabled.
showSecondsbooleanfalseDisplay and edit seconds; otherwise seconds are zero.
use12HoursbooleanfalseUse a 12-hour clock with AM/PM.
minuteStepnumber1Minute segment step and column interval, retaining existing off-step values.
secondStepnumber1Second segment step and column interval, retaining existing off-step values.
openboolean—Control whether the panel is open.
defaultOpenboolean—Initial open state.
onOpenChange(open: boolean) => void—Called when the panel opens or closes.
panelVariant'plain' | 'card''plain'Panel appearance; card places the content on an inset surface above a muted canvas.
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—Placement relative to the trigger.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—Custom popup styles.
popupRender(content: React.ReactNode) => React.ReactNode—Wrap or extend popup content; retain the supplied content to preserve interaction.
getPopupContainer() => Element | DocumentFragment—Return a popup container, including a ShadowRoot.