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 for time, or DateRangePicker for a range.

basic.tsx

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

export function DatePickerBasic() {
  return (
    <Form layout="vertical">
      <FormField label="Choose a date">
        <DatePicker aria-label="Choose a date" placeholder="Pick a good day" />
      </FormField>
      <FormField label="Default date">
        <DatePicker aria-label="Default date" defaultValue={new Date(2026, 9, 15)} />
      </FormField>
      <FormField label="Disabled date">
        <DatePicker aria-label="Disabled date" defaultValue={new Date(2026, 9, 15)} disabled />
      </FormField>
    </Form>
  );
}

controlled.tsx

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

import { useState } from 'react';

export function DatePickerControlled() {
  const [date, setDate] = useState<Date | null>(new Date(2026, 9, 15));
  const [dateString, setDateString] = useState('2026-10-15');
  return (
    <Form layout="vertical">
      <FormField label="Date in October">
        <DatePicker
          aria-label="Date in October"
          value={date}
          minDate={new Date(2026, 9, 5)}
          maxDate={new Date(2026, 9, 25)}
          onChange={(next, text) => {
            setDate(next);
            setDateString(text);
          }}
        />
      </FormField>
      <Text tone="muted">October 5–25 are available. Current:{dateString || 'Not selected'}</Text>
      <FormField label="Required date · Error">
        <DatePicker
          aria-label="Required date"
          status="error"
          required
          placeholder="Set a deadline"
        />
      </FormField>
    </Form>
  );
}

Date shortcuts

Customize Today with todayText, add shortcuts with renderExtraFooter, or hide Today with showToday=false.

Custom date shortcuts

footer.tsx

import { Button, DatePicker, Flex, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function DatePickerFooter() {
  const [value, setValue] = useState<Date | null>(null);
  const tomorrow = () => {
    const next = new Date();
    next.setDate(next.getDate() + 1);
    next.setHours(0, 0, 0, 0);
    setValue(next);
  };
  return (
    <Flex direction="column" gap="sm" align="start">
      <Text>Custom date shortcuts</Text>
      <DatePicker
        aria-label="Custom date shortcuts"
        value={value}
        onChange={setValue}
        todayText="Today"
        renderExtraFooter={
          <Button variant="ghost" size="sm" onClick={tomorrow}>
            Tomorrow
          </Button>
        }
      />
    </Flex>
  );
}

Extended features

Year

Quarter

Month

Week

extensions.tsx

import { DatePicker, Space } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <Space wrap>
      {(['year', 'quarter', 'month', 'week'] as const).map((picker) => (
        <label key={picker} htmlFor={`period-${picker}`}>
          {{ year: 'Year', quarter: 'Quarter', month: 'Month', week: 'Week' }[picker]}
          <DatePicker id={`period-${picker}`} picker={picker} />
        </label>
      ))}
    </Space>
  );
}

Formats, presets and multiple dates

Custom display and weekday restrictions

Select up to three dates

capabilities.tsx

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

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm" align="center">
        <Text>
          {'Custom display and weekday restrictions'}
        </Text>
        <DatePicker
          format="DD/MM/YYYY"
          disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
          presets={[{ label: 'Today', value: () => new Date() }]}
        />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        <Text>{'Select up to three dates'}</Text>
        <DatePicker multiple maxCount={3} format="MM/DD" />
      </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.

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[]`	—	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<HTMLInputElement>`	—	DOM reference

Types

Import DatePickerProps to describe component props. Option types in the API table link to their detailed fields above.

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 for labels, help and errors. ConfigProvider 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[]`	—	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.

#DatePicker

#Examples

#Date shortcuts

#Extended features

#Formats, presets and multiple dates

#Serialization and dates

#DatePicker API

#Types

#Forms and localization

#SingleDatePicker API

#MultipleDatePicker API

#DatePreset