> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/date-picker.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# DatePicker

Choose a date, time or date and time. Calendar modes use local `Date` values; `picker="time"` uses time strings. Use [DateRangePicker](https://ifhover.github.io/leaf-ui/en/components/date-range-picker.md) for ranges.


## Basic usage

Set an initial date with `defaultValue`; choosing a date closes the panel. Use `null` for an empty value.


Default 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 (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Default date">
        <DatePicker defaultValue={new Date(2026, 9, 15)} />
      </FormField>
    </Form>
  );
}
```

Expand code


## Examples

### Controlled value and clearing

Manage selection with `value` and `onChange`. Calendar modes provide both a `Date` and a formatted string; clearing returns `null` and `''`. Reset application state when resetting a controlled form field.


Deadline

Callback text: 2026-10-15Reset

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/controlled.tsx"
import { Button, DatePicker, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const initialDate = new Date(2026, 9, 15);

export function DatePickerControlled() {
  const [value, setValue] = useState<Date | null>(initialDate);
  const [dateString, setDateString] = useState('2026-10-15');

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => event.preventDefault()}
      onReset={() => {
        setValue(initialDate);
        setDateString('2026-10-15');
      }}
    >
      <FormField label="Deadline">
        <DatePicker
          value={value}
          onChange={(next, text) => {
            setValue(next);
            setDateString(text);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        Callback text: {dateString || 'Empty string'}
      </Text>
      <Button type="reset">Reset</Button>
    </Form>
  );
}
```

Expand code

### Interaction states

`disabled` disables the whole control. `readOnly` keeps a read-only value that cannot be changed. `inputReadOnly` prevents typing but still allows panel selection.


Disabled

Read-only

Panel selection only

states.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/states.tsx"
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DatePickerStates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Disabled">
        <DatePicker defaultValue={new Date(2026, 9, 15)} disabled />
      </FormField>
      <FormField label="Read-only">
        <DatePicker defaultValue={new Date(2026, 9, 15)} readOnly />
      </FormField>
      <FormField label="Panel selection only">
        <DatePicker defaultValue={new Date(2026, 9, 15)} inputReadOnly />
      </FormField>
    </Form>
  );
}
```

Expand code

### Picker granularity

Use `picker` to select a year, quarter, month or week. The returned `Date` is the start of that period. [ConfigProvider](https://ifhover.github.io/leaf-ui/en/components/config-provider.md) sets the first weekday with `weekStartsOn`, defaulting to Monday.


Year

Quarter

Month

Week

extensions.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/extensions.tsx"
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      {(['year', 'quarter', 'month', 'week'] as const).map((picker) => (
        <FormField
          key={picker}
          label={{ year: 'Year', quarter: 'Quarter', month: 'Month', week: 'Week' }[picker]}
        >
          <DatePicker picker={picker} />
        </FormField>
      ))}
    </Form>
  );
}
```

Expand code

### Restrict selectable dates

`minDate` / `maxDate` include their boundaries, and returning `true` from `disabledDate` disables a date. This example allows weekdays in October only. Restrictions apply to typing and panel selection without clearing an existing value; revalidate it in the application when business rules change. Datetime mode compares complete timestamps against its bounds.


Weekday in October

disabled-dates.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/disabled-dates.tsx"
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DisabledDates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Weekday in October">
        <DatePicker
          defaultValue={new Date(2026, 9, 15)}
          minDate={new Date(2026, 9, 1)}
          maxDate={new Date(2026, 9, 31)}
          disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
        />
      </FormField>
    </Form>
  );
}
```

Expand code

### Date and time

With `picker="datetime"`, choose a date and time, then select OK to commit. This mode defaults to `needConfirm={true}`; an outside click discards an unconfirmed date and time.


Appointment

datetime.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/datetime.tsx"
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DatePickerDateTime() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Appointment">
        <DatePicker picker="datetime" defaultValue={new Date(2026, 9, 3, 14, 30)} />
      </FormField>
    </Form>
  );
}
```

Expand code

### Time only

`picker="time"` uses 24-hour `HH:mm` strings for its value and `onChange`, returning `null` when cleared. With `showSeconds`, it uses `HH:mm:ss`. Set `minTime` / `maxTime` for time bounds, or `disabledTime` for business restrictions.


Default time

time.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/time.tsx"
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DatePickerTime() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Default time">
        <DatePicker picker="time" defaultValue="09:30" />
      </FormField>
    </Form>
  );
}
```

Expand code

### 12-hour time and seconds

`use12Hours` changes display only; values remain in 24-hour format. `minuteStep` / `secondStep` set adjustment steps while retaining existing off-step values. When seconds are hidden, committed seconds are `0`.


12-hour clock

Include seconds

twelve-hours.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/twelve-hours.tsx"
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DatePickerTwelveHours() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="12-hour clock">
        <DatePicker picker="time" use12Hours defaultValue="14:30" />
      </FormField>
      <FormField label="Include seconds">
        <DatePicker picker="time" use12Hours showSeconds secondStep={10} defaultValue="00:05:30" />
      </FormField>
    </Form>
  );
}
```

Expand code

### Display format and form submission

[](#)
`format` changes display and the string argument of `onChange`, not the canonical FormData value. This example displays `DD/MM/YYYY` and submits `YYYY-MM-DD`. Clearing submits an empty string; resetting an uncontrolled field restores `defaultValue`.


Meeting date

SubmitReset

FormData: Not submitted

format.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/format.tsx"
import { Button, DatePicker, Form, FormField, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function Format() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(String(new FormData(event.currentTarget).get('meetingDate') ?? ''));
      }}
      onReset={() => setSubmitted(null)}
    >
      <FormField label="Meeting date">
        <DatePicker name="meetingDate" format="DD/MM/YYYY" defaultValue={new Date(2026, 9, 15)} />
      </FormField>
      <Space>
        <Button type="submit">Submit</Button>
        <Button type="reset">Reset</Button>
      </Space>
      <Text tone="muted" role="status">
        FormData: {submitted === null ? 'Not submitted' : JSON.stringify(submitted)}
      </Text>
    </Form>
  );
}
```

Expand code

Canonical values are `date: YYYY-MM-DD`, `year: YYYY`, `quarter: YYYY-QN`, `month: YYYY-MM` and `week: YYYY-Www`; datetime uses `YYYY-MM-DD HH:mm[:ss]`. Dates use local time. Handle business timezone conversion in the application rather than treating UTC date strings as local calendar values.

String formats support `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss` and `Q`. Escape literals with brackets, for example `YYYY-[Q]Q`. If a function formatter produces text the default parser cannot recognize, provide `parse`, returning `null` on failure. See [Form](https://ifhover.github.io/leaf-ui/en/components/form.md) for other form configuration.

### Date shortcuts

Use `presets` for common dates. Values may be a `Date` or a function that synchronously returns a `Date`, not a Promise. Choosing a valid preset commits immediately and closes the panel without waiting for OK. Configure Today with `showToday` / `todayText`; use `renderExtraFooter` for custom footer content and handle its business actions in the application.


Delivery date

presets.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-picker/presets.tsx"
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

function tomorrow() {
  const date = new Date();
  date.setDate(date.getDate() + 1);
  date.setHours(0, 0, 0, 0);
  return date;
}

export function DatePickerPresets() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Delivery date">
        <DatePicker presets={[{ label: 'Tomorrow', value: tomorrow }]} />
      </FormField>
    </Form>
  );
}
```

Expand code

#### Input and confirmation

Type or paste a complete value, and select date segments with the mouse or Left / Right. Enter commits valid input; Escape discards the current edit. Invalid or incomplete input reverts to the committed value when focus leaves the whole picker. Alt + ArrowDown moves focus into the panel.

Date and time-only modes do not require confirmation by default; valid changes may commit when focus leaves. With `needConfirm`, unconfirmed edits are discarded on dismissal. Clearing and presets still commit directly.


## API

### DatePicker API

The main table includes props for different `picker` modes: `format`, `parse`, `presets`, `minDate` / `maxDate` and calendar display props apply to calendar modes; `minTime` / `maxTime` apply to time-only mode. In datetime mode, `disabledTime` also receives the current `Date`.

| Property            | Type                                                                                                                                                                 | Default                 | Description                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------- |
| `picker`            | `'date' \| 'datetime' \| 'year' \| 'quarter' \| 'month' \| 'week' \| 'time'`                                                                                         | `'date'`                | Select a date, time, date-time, week, month, quarter or year.                                  |
| `value`             | `Date \| null \| string`                                                                                                                                             | —                       | Controlled value: Date for dates/date-times, HH:mm\[:ss] string for time; null when empty.     |
| `defaultValue`      | `Date \| null \| string`                                                                                                                                             | `null`                  | Initial uncontrolled value, matching picker, restored on form reset.                           |
| `onChange`          | `((value: Date \| null, dateString: string) => void) \| ((value: string \| null) => void)`                                                                           | —                       | Called on commit: Date and formatted string for date modes, only HH:mm\[:ss] or null for time. |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`                  | Control size                                                                                   |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —                       | Validation appearance                                                                          |
| `disabled`          | `boolean`                                                                                                                                                            | `false`                 | Disable interaction.                                                                           |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —                       | Disable typing while retaining panel selection.                                                |
| `allowClear`        | `boolean`                                                                                                                                                            | `true`                  | Show a clear button                                                                            |
| `minDate`           | `Date`                                                                                                                                                               | —                       | Earliest selectable date; datetime compares the complete timestamp, inclusive.                 |
| `maxDate`           | `Date`                                                                                                                                                               | —                       | Latest selectable date; datetime compares the complete timestamp, inclusive.                   |
| `disabledDate`      | `(date: Date) => boolean`                                                                                                                                            | —                       | Restrict selectable dates                                                                      |
| `minTime`           | `string`                                                                                                                                                             | —                       | Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.                                     |
| `maxTime`           | `string`                                                                                                                                                             | —                       | Latest selectable time, inclusive, as HH:mm or HH:mm:ss.                                       |
| `disabledTime`      | `((parts: `[`TimeParts`](#timeparts)`, date: Date) => boolean) \| ((parts: `[`TimeParts`](#timeparts)`) => boolean)`                                                 | —                       | Disable times; typing and panel selection use the same rules.                                  |
| `needConfirm`       | `boolean`                                                                                                                                                            | `picker === "datetime"` | Require OK or Enter to commit; discard the draft on blur when enabled.                         |
| `showSeconds`       | `boolean`                                                                                                                                                            | `false`                 | Display and edit seconds; otherwise seconds are zero.                                          |
| `use12Hours`        | `boolean`                                                                                                                                                            | `false`                 | Use a 12-hour clock with AM/PM.                                                                |
| `minuteStep`        | `number`                                                                                                                                                             | `1`                     | Minute segment step and column interval, retaining existing off-step values.                   |
| `secondStep`        | `number`                                                                                                                                                             | `1`                     | Second segment step and column interval, retaining existing off-step values.                   |
| `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.                                                      |
| `showToday`         | `boolean`                                                                                                                                                            | `true`                  | Show the Today shortcut                                                                        |
| `todayText`         | `ReactNode`                                                                                                                                                          | Locale default          | Customize the Today label                                                                      |
| `renderExtraFooter` | `ReactNode`                                                                                                                                                          | —                       | Additional footer content                                                                      |
| `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.                                                               |
| `open`              | `boolean`                                                                                                                                                            | —                       | Control whether the panel is open.                                                             |
| `defaultOpen`       | `boolean`                                                                                                                                                            | —                       | Initial open state.                                                                            |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —                       | Calendar open-state changes                                                                    |
| `panelVariant`      | `'plain' \| 'card'`                                                                                                                                                  | `'plain'`               | Panel appearance; card places the content on an inset surface above a muted canvas.            |
| `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.                                    |
| `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.                                              |
| `ref`               | `Ref<HTMLInputElement>`                                                                                                                                              | —                       | DOM reference                                                                                  |

Other native input attributes and `aria-*` target the input; `className` / `style` target the wrapper. See [PopupOptions](https://ifhover.github.io/leaf-ui/en/api/popup-options.md) for shared popup configuration.

### SingleDatePicker API

Value and callback types for calendar modes; see the main table for shared props.

| Property       | Type                                                | Default | Description                                                                                |
| -------------- | --------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `value`        | `Date \| null`                                      | —       | Controlled value.                                                                          |
| `defaultValue` | `Date \| null`                                      | `null`  | Initial value; uncontrolled fields support native form reset.                              |
| `onChange`     | `(value: Date \| null, dateString: string) => void` | —       | Return the date and formatted string on commit; clearing returns null and an empty string. |

### DatePreset

Preset entries used by `presets`. `T` is `Date` for a single value or a date tuple for a range. Functions must be synchronous, free of side effects and safe to evaluate repeatedly.

| Property | Type             | Default  | Description                                                                                 |
| -------- | ---------------- | -------- | ------------------------------------------------------------------------------------------- |
| `key`    | `string`         | —        | Stable, unique identifier.                                                                  |
| `label`  | `ReactNode`      | Required | Visible label or content.                                                                   |
| `value`  | `T \| (() => T)` | Required | Preset value or synchronous function; functions must be pure and allow repeated evaluation. |

### TimePickerMode API

Props and callbacks for `picker="time"`; values always use 24-hour strings.

| Property            | Type                                                                                                                                                                 | Default   | Description                                                                         |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------- |
| `picker`            | `'time'`                                                                                                                                                             | Required  | Time-only mode; pass time.                                                          |
| `value`             | `string \| null`                                                                                                                                                     | —         | Controlled 24-hour HH:mm or HH:mm:ss string; null when empty.                       |
| `defaultValue`      | `string \| null`                                                                                                                                                     | `null`    | Initial value; uncontrolled fields support native form reset.                       |
| `onChange`          | `(value: string \| null) => void`                                                                                                                                    | —         | Return only a 24-hour string on commit, or null on clear.                           |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`    | Presentation size.                                                                  |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —         | Show an error or warning appearance without performing validation.                  |
| `allowClear`        | `boolean`                                                                                                                                                            | `true`    | Show a clear action.                                                                |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —         | Disable typing while retaining panel selection.                                     |
| `minTime`           | `string`                                                                                                                                                             | —         | Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.                          |
| `maxTime`           | `string`                                                                                                                                                             | —         | Latest selectable time, inclusive, as HH:mm or HH:mm:ss.                            |
| `disabledTime`      | `(parts: `[`TimeParts`](#timeparts)`) => boolean`                                                                                                                    | —         | Disable times; typing and panel selection use the same rules.                       |
| `needConfirm`       | `boolean`                                                                                                                                                            | `false`   | Require OK or Enter to commit; discard the draft on blur when enabled.              |
| `showSeconds`       | `boolean`                                                                                                                                                            | `false`   | Display and edit seconds; otherwise seconds are zero.                               |
| `use12Hours`        | `boolean`                                                                                                                                                            | `false`   | Use a 12-hour clock with AM/PM.                                                     |
| `minuteStep`        | `number`                                                                                                                                                             | `1`       | Minute segment step and column interval, retaining existing off-step values.        |
| `secondStep`        | `number`                                                                                                                                                             | `1`       | Second segment step and column interval, retaining existing off-step values.        |
| `open`              | `boolean`                                                                                                                                                            | —         | Control whether the panel is open.                                                  |
| `defaultOpen`       | `boolean`                                                                                                                                                            | —         | Initial open state.                                                                 |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —         | Called when the panel opens or closes.                                              |
| `panelVariant`      | `'plain' \| 'card'`                                                                                                                                                  | `'plain'` | Panel appearance; card places the content on an inset surface above a muted canvas. |
| `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.                                   |

### TimeParts

Time parts passed to `disabledTime`.

| Property | Type     | Default  | Description                        |
| -------- | -------- | -------- | ---------------------------------- |
| `hour`   | `number` | Required | Hour as an integer from 0 to 23.   |
| `minute` | `number` | Required | Minute as an integer from 0 to 59. |
| `second` | `number` | Required | Second as an integer from 0 to 59. |
