Date Picker

Installation

npx baseui-cn@latest add date-picker

The registry item installs the component, its token-based stylesheet, and the required DayPicker and date-fns dependencies.

Usage

import {
  DatePicker,
  DatePickerInput,
  DateRangePicker,
  DateRangePickerInput,
} from "@/components/ui/date-picker"

Use DatePicker and DateRangePicker when the calendar should remain visible. Use the input variants for forms, filters, and compact layouts where the calendar belongs in a popover.

const [date, setDate] = React.useState<Date>()

<DatePickerInput value={date} onValueChange={setDate} />

Examples

Single date inline

DatePicker renders only the calendar and keeps values as Date objects.

For an inline multi-select calendar, set mode="multiple"; its value and callback use Date[].

Single date input

DatePickerInput combines the standard Input surface, an accessible read-only trigger, Base UI Popover, clear action, and calendar. Pass label to use the standard Field label treatment. It closes after a selection by default.

Display formats

Use a built-in formatPreset for common formats. A custom displayFormat is a date-fns format string and takes precedence over the preset.

<DatePickerInput formatPreset="short" />
<DatePickerInput formatPreset="long" />
<DatePickerInput displayFormat="dd MMM yyyy" />
<DateRangePickerInput formatPreset="medium" rangeSeparator=" to " />

Date range inline

DateRangePicker supports one to three visible months. Two months are shown by default.

Date range input

The range input keeps a draft selection while open. Its visible value follows that draft immediately, including partial and preset selections. Cancel restores the committed value, while Apply commits the draft.

Presets

Built-in presets include today, yesterday, the last 7 and 30 days, this month, last month, and year to date. Pass your own DateRangePreset[] to replace them.

const presets = [
  {
    label: "Next 14 days",
    getValue: () => ({ from: new Date(), to: addDays(new Date(), 13) }),
  },
]

<DateRangePickerInput presets={presets} />

Single date form

This Base UI form keeps the selected value as a Date, validates it on submit, and reports the formatted result with the standard toast component. The hidden ISO value is only the serialized transport value for backend submission; picker state remains a Date.

Date range form

Range forms keep { from?: Date; to?: Date } in state. The example serializes from and to into separate hidden ISO values when a backend form submission needs strings.

Sizes

The sm, md, and lg sizes apply to both the trigger and calendar.

Disabled dates and boundaries

Use minDate and maxDate for navigation and selection boundaries. disabledDates accepts any DayPicker matcher or matcher array.

Month and year switcher

Select the caption to move from days to years, then months. startMonth and endMonth also limit the custom switcher.

Controlled value

Formatting helpers

The module exports getDateFormat, formatDateValue, formatDateRangeValue, formatDate, formatDateRange, isValidDate, and normalizeMonth. Formatting is display-only; the source of truth remains Date objects. Input variants intentionally use a read-only Input surface instead of guessing how locale-specific typed input should be parsed.

Styling

date-picker.styles.css maps DayPicker variables to the standard baseui-cn tokens, including --background, --popover, --primary, --accent, --border, and --ring. Override DayPicker internals with classNames, the outer calendar with className, or the input surfaces with triggerClassName, popoverClassName, and calendarClassName.

API

DatePicker

DatePicker defaults to mode="single". With mode="multiple", value, defaultValue, and onValueChange use Date[] instead.

DatePickerInput

Accepts the DatePicker props plus label, placeholder, formatPreset, displayFormat, clearable, closeOnSelect, open, defaultOpen, and onOpenChange. displayFormat overrides formatPreset; the default preset is medium.

DateRangePicker

DateRangePickerInput

Accepts the range picker props plus label, startLabel, endLabel, placeholder, startPlaceholder, endPlaceholder, rangeSeparator, formatPreset, and displayFormat. Presets and the footer default to visible, and the control displays draft changes immediately until they are applied or canceled.