DatePicker
Enter a date as text or choose one from a calendar popover.
Component behavior
DatePicker selects one calendar date through text input or a calendar popover. Focusing the input opens the popover.
- Single-day form inputs such as expiry or scheduling dates.
- Dates entered through text or calendar selection.
- Date selection constrained by minimum and maximum values.
DateRangeField: the field accepts a start and end date and may be empty.
DateRangePicker: a toolbar filter selects date ranges using presets.
MiniCalendar: the calendar remains visible and selection is application-controlled.
Input: time-of-day or timestamp entry is required. DatePicker emits dates at local midnight.
Props
Selection produces a Date at local midnight. Use value and onChange for controlled state or defaultValue for internal state. Use null for an empty controlled value. value={undefined} enables internal state.
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | null | — | Controlled value. null is empty; undefined switches the component to uncontrolled. |
defaultValue | Date | null | — | Initial value when uncontrolled. Defaults to null. |
onChange | (date: Date | null) => void | — | Fires on grid click, preset click, a committed edit, and clear. Called in both controlled and uncontrolled mode. |
min | Date | — | Earliest selectable day. Clicks on earlier days are ignored; those days are not disabled. |
max | Date | — | Latest selectable date. Typed values outside [min, max] are discarded on commit and the field reverts. |
placeholder | string | "Pick a date" | Placeholder text when empty. |
format | (date: Date) => string | — | Display formatter. Defaults to formatDate. Does not affect accepted input formats. |
disabled | boolean | — | Disables the input and the calendar button, and hides the clear button. |
clearable | boolean | true | Shows an X that sets the value to null. Only rendered when a value is set and the picker is not disabled. |
presets | { label: string; date: () => Date }[] | — | Quick rows above the calendar. Each date() is evaluated on click, so relative presets stay correct. Clicking one sets the value and closes the popover. |
align | "start" | "end" | "start" | Popover alignment relative to the trigger: bottom-start or bottom-end. |
size | "sm" | "md" | "md" | Control height. |
className | string | — | Targets the field container, not the input. |
id | string | — | HTML id on the input, for a Field label's htmlFor. |
Examples
Typing and picking
Typing updates an internal draft. Enter or blur commits it; Escape discards it and closes the popover. parseDate accepts ISO dates, month-first slash forms, and named-month forms. A missing year uses the current year. Empty text commits null. Invalid text marks the field invalid and restores the last valid value on commit.
Bounded window
min and max include their boundary days. Calendar clicks outside the range are ignored. Typed dates outside the range are discarded on commit. Explain the range in a Field hint; rejected dates do not generate an announcement.
Presets
A preset provides a label and a function evaluated on click. DEFAULT_DATE_PRESETS contains Today, Tomorrow, and Next Monday. Preset dates use local midnight. Selecting a preset closes the popover.
Compact, fixed format
size="sm" uses the toolbar height. Set format for the required date representation and clearable={false} to disable clearing. The ISO display format is accepted by parseDate.
import {
DatePicker,
DEFAULT_DATE_PRESETS,
formatDate,
parseDate,
} from "@solarius/onset";
import type { DatePickerProps } from "@solarius/onset";