> 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-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. # DatePicker Choose a date from a calendar. ## Examples Values are Date objects in local time. onChange also supplies the formatted string for the current picker mode; named fields submit this string. Arrow keys move days, Home / End move within a week, and PageUp / PageDown move months. Use [DateTimePicker](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/date-time-picker.md) for time, or [DateRangePicker](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/date-range-picker.md) for a range. Choose a date Default date Disabled date basic.tsx Copy code ```tsx lineNumbers file="../../../src/examples/en/date-picker/basic.tsx" import { DatePicker, Form, FormField } from '@ifhover/leaf-ui'; export function DatePickerBasic() { return (
); } ``` Expand code Date in October October 5–25 are available. Current:2026-10-15 Required date · Error controlled.tsx Copy code ```tsx lineNumbers file="../../../src/examples/en/date-picker/controlled.tsx" import { DatePicker, Form, FormField, Text } from '@ifhover/leaf-ui'; import { useState } from 'react'; export function DatePickerControlled() { const [date, setDate] = useState(new Date(2026, 9, 15)); const [dateString, setDateString] = useState('2026-10-15'); return (
{ setDate(next); setDateString(text); }} /> October 5–25 are available. Current:{dateString || 'Not selected'}
); } ``` Expand code ## Date shortcuts Customize Today with todayText, add shortcuts with renderExtraFooter, or hide Today with showToday=false. Custom date shortcuts footer.tsx Copy code ```tsx lineNumbers file="../../../src/examples/en/date-picker/footer.tsx" import { Button, DatePicker, Flex, Text } from '@ifhover/leaf-ui'; import { useState } from 'react'; export function DatePickerFooter() { const [value, setValue] = useState(null); const tomorrow = () => { const next = new Date(); next.setDate(next.getDate() + 1); next.setHours(0, 0, 0, 0); setValue(next); }; return ( Custom date shortcuts Tomorrow } /> ); } ``` Expand code ## Extended features YearQuarterMonthWeek extensions.tsx Copy code ```tsx lineNumbers file="../../../src/examples/en/date-picker/extensions.tsx" import { DatePicker, Space } from '@ifhover/leaf-ui'; export function ExtensionDemo() { return ( {(['year', 'quarter', 'month', 'week'] as const).map((picker) => ( ))} ); } ``` Expand code ## Formats, presets and multiple dates Custom display and weekday restrictions Select up to three dates capabilities.tsx Copy code ```tsx lineNumbers file="../../../src/examples/date-picker/capabilities.tsx" import { DatePicker, Flex, Space, Text } from '@ifhover/leaf-ui'; export function Capabilities() { return ( {'Custom display and weekday restrictions'} date.getDay() === 0 || date.getDay() === 6} presets={[{ label: 'Today', value: () => new Date() }]} /> {'Select up to three dates'} ); } ``` 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`. ## DatePicker 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 a clear button | | `inputReadOnly` | `boolean` | — | Disable typing while retaining panel selection. | | `open` | `boolean` | — | Control whether the panel is open. | | `defaultOpen` | `boolean` | — | Initial open state. | | `multiple` | `false \| true` | — | Enable multiple selection; value and callback types change accordingly. | | `value` | `Date \| null \| readonly Date[]` | `null` | Controlled date / initial uncontrolled date | | `defaultValue` | `Date \| null \| readonly Date[]` | `null` | Controlled date / initial uncontrolled date | | `minDate` | `Date` | — | Earliest / latest date, compared in local time | | `maxDate` | `Date` | — | Earliest / latest date, compared in local time | | `picker` | `'date' \| 'year' \| 'quarter' \| 'month' \| 'week'` | `'date'` | Select date, year, quarter, month or week | | `disabledDate` | `(date: Date) => boolean` | — | Restrict selectable dates | | `showToday` | `boolean` | `true` | Show the Today shortcut | | `todayText` | `ReactNode` | Locale default | Customize the Today label | | `renderExtraFooter` | `ReactNode` | — | Additional footer content | | `onChange` | `((value: Date \| null, dateString: string) => void) \| ((value: Date[], dateStrings: string[]) => void)` | — | Changed date; clearing returns null and an empty string | | `onOpenChange` | `(open: boolean) => void` | — | Calendar open-state changes | | `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`](#datepreset)`[]` | — | Presets; value may be computed on demand. | | `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. | | `maxCount` | `number` | — | Maximum selection count. | | `disabled` | `boolean` | `false` | Disable interaction. | | `name` | `string` | — | Field name in native FormData. | | `form` | `string` | — | ID of the associated native form. | | `required` | `boolean` | `false` | Require a non-empty value; compound controls validate once. | | `ref` | `Ref` | — | DOM reference | ## Types Import DatePickerProps to describe component props. Option types in the API table link to their detailed fields above. ```ts import type { DatePickerProps } from '@ifhover/leaf-ui'; ``` ## Forms and localization Use name to include values in FormData. Uncontrolled fields follow form reset; reset controlled values in application state. Place controls in [FormField](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/form.md#formfield-api) for labels, help and errors. [ConfigProvider](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/config-provider.md) supplies regional themes and translated built-in UI. Application labels and options are your responsibility. Type `YYYY-MM-DD` and press Enter or move focus away to submit. Invalid dates and values outside minDate/maxDate are rejected. Click the month or year heading to switch panels. Today selects the current date. Use showToday, todayText and renderExtraFooter to customize shortcuts. Clicking the field keeps typing focus; ArrowDown moves into the calendar, and Escape discards pending text. Other input attributes and aria-\* target the input; className/style target the wrapper. Picker formats: `date → YYYY-MM-DD`, `year → YYYY`, `quarter → YYYY-QN`, `month → YYYY-MM`, `week → YYYY-Www`. These formats apply to display, manual input, the onChange string and FormData. ## SingleDatePicker 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'` | Presentation size. | | `status` | `'error' \| 'warning'` | — | Configure status. | | `allowClear` | `boolean` | `true` | Show a clear action. | | `inputReadOnly` | `boolean` | — | Disable typing while retaining panel selection. | | `open` | `boolean` | — | Control whether the panel is open. | | `defaultOpen` | `boolean` | — | Initial open state. | | `multiple` | `false` | — | Enable multiple selection; value and callback types change accordingly. | | `value` | `Date \| null` | — | Controlled value. | | `defaultValue` | `Date \| null` | `null` | Initial value; uncontrolled fields support native form reset. | | `minDate` | `Date` | — | Earliest available date, inclusive. | | `maxDate` | `Date` | — | Latest available date, inclusive. | | `picker` | `'date' \| 'year' \| 'quarter' \| 'month' \| 'week'` | `'date'` | Configure picker. | | `disabledDate` | `(date: Date) => boolean` | — | Disable dates using business rules. | | `showToday` | `boolean` | `true` | Configure show today. | | `todayText` | `ReactNode` | — | Configure today text. | | `renderExtraFooter` | `ReactNode` | — | Configure render extra footer. | | `onChange` | `(value: Date \| null, dateString: string) => void` | — | Called when the value changes. | | `onOpenChange` | `(open: boolean) => void` | — | Called when the panel opens or closes. | | `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`](#datepreset)`[]` | — | Presets; value may be computed on demand. | | `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. | ## MultipleDatePicker 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'` | Presentation size. | | `status` | `'error' \| 'warning'` | — | Configure status. | | `allowClear` | `boolean` | `true` | Show a clear action. | | `inputReadOnly` | `boolean` | — | Disable typing while retaining panel selection. | | `open` | `boolean` | — | Control whether the panel is open. | | `defaultOpen` | `boolean` | — | Initial open state. | | `minDate` | `Date` | — | Earliest available date, inclusive. | | `maxDate` | `Date` | — | Latest available date, inclusive. | | `picker` | `'date' \| 'year' \| 'quarter' \| 'month' \| 'week'` | `'date'` | Configure picker. | | `disabledDate` | `(date: Date) => boolean` | — | Disable dates using business rules. | | `showToday` | `boolean` | `true` | Configure show today. | | `todayText` | `ReactNode` | — | Configure today text. | | `renderExtraFooter` | `ReactNode` | — | Configure render extra footer. | | `onOpenChange` | `(open: boolean) => void` | — | Called when the panel opens or closes. | | `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. | | `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. | | `multiple` | `true` | — | Required. Enable multiple selection; value and callback types change accordingly. | | `value` | `readonly Date[]` | — | Controlled value. | | `defaultValue` | `readonly Date[]` | — | Initial value; uncontrolled fields support native form reset. | | `maxCount` | `number` | — | Maximum selection count. | | `onChange` | `(value: Date[], dateStrings: string[]) => void` | — | Called when the value changes. | ## DatePreset | Property | Type | Default | Description | | -------- | ---------------- | ------- | ----------------------------------- | | `key` | `string` | — | Stable, unique identifier. | | `label` | `ReactNode` | — | Required. Visible label or content. | | `value` | `T \| (() => T)` | — | Required. Controlled value. |