DateRangePicker

Select start and end dates or times to define a range.

Controlled range

basic.tsx

import { type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function DateRangePickerBasic() {
  const [range, setRange] = useState<DateRange | null>(null);
  return (
    <Form layout="vertical">
      <FormField label="Date range">
        <DateRangePicker aria-label="Date range" value={range} onChange={setRange} />
      </FormField>
      {range && (
        <output>
          <Text tone="muted">
            {range[0].toLocaleDateString()} – {range[1].toLocaleDateString()}
          </Text>
        </output>
      )}
    </Form>
  );
}

Picker modes

modes.tsx

import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerModes() {
  return (
    <Form layout="vertical">
      <FormField label="Year range">
        <DateRangePicker aria-label="Year range" picker="year" placeholder="Year range" />
      </FormField>
      <FormField label="Month range">
        <DateRangePicker aria-label="Month range" picker="month" placeholder="Month range" />
      </FormField>
      <FormField label="Week range">
        <DateRangePicker aria-label="Week range" picker="week" placeholder="Week range" />
      </FormField>
      <FormField label="Date and time range">
        <DateRangePicker
          aria-label="Date and time range"
          picker="datetime"
          placeholder="Date and time range"
          use12Hours
        />
      </FormField>
    </Form>
  );
}

Quarters, presets and open endpoints

Quarter range

Allow an open end, or use a recent-seven-day preset

capabilities.tsx

import { DateRangePicker, Flex, Space, Text } from '@ifhover/leaf-ui';

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm" align="center">
        <Text>{'Quarter range'}</Text>
        <DateRangePicker picker="quarter" format="YYYY-[Q]Q" />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        {'Allow an open end, or use a recent-seven-day preset'}
        <DateRangePicker
          allowEmpty={[false, true]}
          disabledDate={(date) => date.getDay() === 0}
          presets={[
            {
              label: 'Recent 7 days',
              value: () => {
                const end = new Date();
                const start = new Date();
                start.setDate(start.getDate() - 6);
                return [start, end];
              },
            },
          ]}
        />
      </Flex>
    </Space>
  );
}

Serialization and dates

format changes display text and the string argument of onChange; FormData keeps the canonical period/date representation described below. Square brackets escape literal text, such as YYYY-[Q]Q. Provide parse with a function-valued formatter. Dates are local calendar values; convert business timezones explicitly at the application boundary. Configure the first weekday with ConfigProvider's weekStartsOn.

DateRangePicker API

Property	Type	Default	Description
`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.
`popupClassName`	`string`	—	Custom class for the popup.
`popupStyle`	`CSSProperties`	—	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.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Control size
`status`	`'error' \| 'warning'`	—	Validation appearance
`allowClear`	`boolean`	`true`	Show the clear button
`inputReadOnly`	`boolean`	—	Disable typing while retaining panel selection.
`open`	`boolean`	—	Control whether the panel is open.
`defaultOpen`	`boolean`	—	Initial open state.
`picker`	`'year' \| 'quarter' \| 'month' \| 'week' \| 'date' \| 'datetime'`	`'date'`	Selection granularity
`minDate`	`Date`	—	Earliest / latest allowed values
`maxDate`	`Date`	—	Earliest / latest allowed values
`use12Hours`	`boolean`	`false`	Display a 12-hour clock with AM/PM options
`showSeconds`	`boolean`	`true`	Include seconds in date-time ranges; otherwise seconds are zero
`minuteStep`	`number`	`1`	Minute / second step, an integer from 1 to 60
`secondStep`	`number`	`1`	Minute / second step, an integer from 1 to 60
`onOpenChange`	`(open: boolean) => void`	—	Called when the panel opens or closes
`disabledDate`	`(date: Date, position: 'start' \| 'end') => boolean`	—	Disable dates using business rules.
`disabledTime`	`(parts: TimeParts, position: 'start' \| 'end', date: Date) => boolean`	—	Disable times; typing and panel selection use the same rules.
`format`	`string \| ((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.
`presets`	`readonly DatePreset<readonly [Date \| null, Date \| null]>[]`	—	Presets; value may be computed on demand.
`onCalendarChange`	`(range: readonly [Date \| null, Date \| null], info: { position: 'start' \| 'end' }) => void`	—	Changes during selection, including the current start/end position.
`panelValue`	`Date`	—	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.
`allowEmpty`	`false \| true \| readonly [boolean, boolean]`	`false`	Explicitly allow open range endpoints.
`value`	`readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| null`	`null`	Controlled / initial range
`defaultValue`	`readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| null`	`null`	Controlled / initial range
`onChange`	`((value: readonly [Date, Date] \| null, dateStrings: readonly [string, string]) => void) \| ((value: readonly [Date \| null, Date \| null] \| null, dateStrings: readonly [string, string]) => void)`	—	Returns an ordered range and formatted strings; clearing returns null
`disabled`	`boolean`	`false`	Disable interaction.
`required`	`boolean`	`false`	Require a non-empty value; compound controls validate once.
`name`	`string`	—	Field name in native FormData.
`form`	`string`	—	ID of the associated native form.
`ref`	`Ref<HTMLInputElement>`	—	Input element reference

DateRange

Property	Type	Default	Description
`0`	`Date`	Required	Start, no later than the end
`1`	`Date`	Required	End

Types

Import types when defining reusable component props or assembling options.

import type { DateRangePickerProps, DateRange } from '@ifhover/leaf-ui';

Usage notes

A DateRange is a readonly [Date, Date]. Years use January 1, months use the first day, and weeks default to Monday; configure weekStartsOn on ConfigProvider with ISO week numbers. Dates use local time.

The two calendars navigate together. After choosing the start, hover a year, month, week or date to preview the range. Choosing the end commits immediately in every mode, without a footer confirmation. Reversed selections are sorted.

For date-time ranges, use the top-right time button in each calendar to set that endpoint's time, then return to the calendar and choose dates. Set times before choosing the end date. Now sets the current time for that endpoint.

With an existing complete range, changing either endpoint's time immediately updates the valid range without reselecting dates.

Type endpoints separated by ~ and press Enter or move focus away. Formats are YYYY, YYYY-MM, YYYY-Www, YYYY-MM-DD and YYYY-MM-DD HH:mm:ss (omit seconds when showSeconds is false). Invalid or out-of-bounds input is not submitted. Escape discards unfinished input.

FormData uses start/end with canonical formats. Uncontrolled fields follow form reset; reset controlled values in application state.

#DateRangePicker

#Controlled range

#Picker modes

#Quarters, presets and open endpoints

#Serialization and dates

#DateRangePicker API

#DateRange

#Types

#Usage notes