DateRangePicker

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

Controlled range

Live previewControlled range

basic.tsx

import { type DateRange, DateRangePicker } from '@sudden3/leaf-ui';
import { useState } from 'react';
export function DateRangePickerBasic() {
  const [range, setRange] = useState<DateRange | null>(null);
  return (
    <div className="leaf-demo-stack">
      <DateRangePicker aria-label="Date range" value={range} onChange={setRange} />
      {range && (
        <output className="leaf-demo-note">
          {range[0].toLocaleDateString()} – {range[1].toLocaleDateString()}
        </output>
      )}
    </div>
  );
}

Picker modes

Live previewPicker modes

modes.tsx

import { DateRangePicker } from '@sudden3/leaf-ui';
export function DateRangePickerModes() {
  return (
    <div className="leaf-demo-stack leaf-demo-stack--wide">
      <DateRangePicker aria-label="Year range" picker="year" placeholder="Year range" />
      <DateRangePicker aria-label="Month range" picker="month" placeholder="Month range" />
      <DateRangePicker aria-label="Week range" picker="week" placeholder="Week range" />
      <DateRangePicker
        aria-label="Date and time range"
        picker="datetime"
        placeholder="Date and time range"
        use12Hours
      />
    </div>
  );
}

DateRangePicker API

Property	Type	Default	Description
`value / defaultValue`	`DateRange \| null`	`null`	Controlled / initial range
`onChange`	`(value: DateRange \| null, dateStrings: readonly [string, string]) => void`	—	Returns an ordered range and formatted strings; clearing returns null
`picker`	`'year' \| 'month' \| 'week' \| 'date' \| 'datetime'`	`'date'`	Selection granularity
`minDate / maxDate`	`Date`	—	Earliest / latest allowed values
`showSeconds`	`boolean`	`true`	Include seconds in date-time ranges; otherwise seconds are zero
`use12Hours`	`boolean`	`false`	Display a 12-hour clock with AM/PM options
`minuteStep / secondStep`	`number`	`1`	Minute / second step, an integer from 1 to 60
`allowClear`	`boolean`	`true`	Show the clear button
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Control size
`status`	`'error' \| 'warning'`	—	Validation appearance
`disabled / required`	`boolean`	`false`	Disabled / required; inherited from FormField
`placeholder / name / form`	`string`	—	Placeholder / field name / form ID
`onOpenChange`	`(open: boolean) => void`	—	Called when the panel opens or closes
`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 '@sudden3/leaf-ui';

Usage notes

A DateRange is a readonly [Date, Date]. Years use January 1, months use the first day, and weeks start on Monday 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

#DateRangePicker API

#DateRange

#Types