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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/date-picker.md.

DatePicker

Choose a date, time or date and time. Calendar modes use local Date values; picker="time" uses time strings. Use DateRangePicker for ranges.

Basic usage

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

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>
  );
}

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.

Callback text: 2026-10-15
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>
  );
}

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.

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>
  );
}

Picker granularity

Use picker to select a year, quarter, month or week. The returned Date is the start of that period. ConfigProvider sets the first weekday with weekStartsOn, defaulting to Monday.

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>
  );
}

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.

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>
  );
}

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.

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>
  );
}

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.

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>
  );
}

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.

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>
  );
}

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.

FormData: Not submitted
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>
  );
}

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 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.

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>
  );
}

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.

PropertyTypeDefaultDescription
picker'date' | 'datetime' | 'year' | 'quarter' | 'month' | 'week' | 'time''date'Select a date, time, date-time, week, month, quarter or year.
valueDate | null | string—Controlled value: Date for dates/date-times, HH:mm[:ss] string for time; null when empty.
defaultValueDate | null | stringnullInitial 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
disabledbooleanfalseDisable interaction.
inputReadOnlyboolean—Disable typing while retaining panel selection.
allowClearbooleantrueShow a clear button
minDateDate—Earliest selectable date; datetime compares the complete timestamp, inclusive.
maxDateDate—Latest selectable date; datetime compares the complete timestamp, inclusive.
disabledDate(date: Date) => boolean—Restrict selectable dates
minTimestring—Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.
maxTimestring—Latest selectable time, inclusive, as HH:mm or HH:mm:ss.
disabledTime((parts: TimeParts, date: Date) => boolean) | ((parts: TimeParts) => boolean)—Disable times; typing and panel selection use the same rules.
needConfirmbooleanpicker === "datetime"Require OK or Enter to commit; discard the draft on blur when enabled.
showSecondsbooleanfalseDisplay and edit seconds; otherwise seconds are zero.
use12HoursbooleanfalseUse a 12-hour clock with AM/PM.
minuteStepnumber1Minute segment step and column interval, retaining existing off-step values.
secondStepnumber1Second segment step and column interval, retaining existing off-step values.
formatstring | ((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.
presetsreadonly DatePreset[]—Presets; value may be computed on demand.
showTodaybooleantrueShow the Today shortcut
todayTextReactNodeLocale defaultCustomize the Today label
renderExtraFooterReactNode—Additional footer content
panelValueDate—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.
openboolean—Control whether the panel is open.
defaultOpenboolean—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.
namestring—Field name in native FormData.
formstring—ID of the associated native form.
requiredbooleanfalseRequire 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.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—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.
refRef<HTMLInputElement>—DOM reference

Other native input attributes and aria-* target the input; className / style target the wrapper. See PopupOptions for shared popup configuration.

SingleDatePicker API

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

PropertyTypeDefaultDescription
valueDate | null—Controlled value.
defaultValueDate | nullnullInitial 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.

PropertyTypeDefaultDescription
keystring—Stable, unique identifier.
labelReactNodeRequiredVisible label or content.
valueT | (() => T)RequiredPreset 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.

PropertyTypeDefaultDescription
picker'time'RequiredTime-only mode; pass time.
valuestring | null—Controlled 24-hour HH:mm or HH:mm:ss string; null when empty.
defaultValuestring | nullnullInitial 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.
allowClearbooleantrueShow a clear action.
inputReadOnlyboolean—Disable typing while retaining panel selection.
minTimestring—Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.
maxTimestring—Latest selectable time, inclusive, as HH:mm or HH:mm:ss.
disabledTime(parts: TimeParts) => boolean—Disable times; typing and panel selection use the same rules.
needConfirmbooleanfalseRequire OK or Enter to commit; discard the draft on blur when enabled.
showSecondsbooleanfalseDisplay and edit seconds; otherwise seconds are zero.
use12HoursbooleanfalseUse a 12-hour clock with AM/PM.
minuteStepnumber1Minute segment step and column interval, retaining existing off-step values.
secondStepnumber1Second segment step and column interval, retaining existing off-step values.
openboolean—Control whether the panel is open.
defaultOpenboolean—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.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—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.

PropertyTypeDefaultDescription
hournumberRequiredHour as an integer from 0 to 23.
minutenumberRequiredMinute as an integer from 0 to 59.
secondnumberRequiredSecond as an integer from 0 to 59.