> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06 > Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/date-range-picker.html > For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms-full.txt. # DateRangePicker Select start and end dates or times to define a range. ## Controlled range Date range basic.tsx Copy code ```tsx lineNumbers file="../../../src/examples/en/date-range-picker/basic.tsx" import { type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui'; import { useState } from 'react'; export function DateRangePickerBasic() { const [range, setRange] = useState(null); return (
{range && ( {range[0].toLocaleDateString()} – {range[1].toLocaleDateString()} )}
); } ``` Expand code ## Picker modes Year range Month range Week range Date and time range modes.tsx Copy code ```tsx lineNumbers file="../../../src/examples/en/date-range-picker/modes.tsx" import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui'; export function DateRangePickerModes() { return (
); } ``` Expand code ## Quarters, presets and open endpoints Quarter range Allow an open end, or use a recent-seven-day preset capabilities.tsx Copy code ```tsx lineNumbers file="../../../src/examples/date-range-picker/capabilities.tsx" import { DateRangePicker, Flex, Space, Text } from '@ifhover/leaf-ui'; export function Capabilities() { return ( {'Quarter range'} {'Allow an open end, or use a recent-seven-day preset'} 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]; }, }, ]} /> ); } ``` Expand code ## 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`](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/time-picker.md#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`](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/date-picker.md#datepreset)`[]` | — | 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` | — | 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. ```ts 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.