Component reference
DatePicker
Single-day selection with a calendar, locale and form integration.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Loading the interactive example?
Width adapts to the available space
"use client";
import { useState } from "react";
import { DatePicker } from "@pimolu/react";
export function DatePickerExample() {
const [value, setValue] = useState<Date | null>(new Date(2026, 9, 21));
return (
<div className="space-y-4">
<DatePicker
label="Launch date"
name="launch-date"
value={value}
onChange={setValue}
locale="en-US"
weekStartsOn={1}
fullWidth
/>
<p role="status">{
value
? `Launch date: ${value.toLocaleDateString("en-US")}`
: "No launch date selected."
}</p>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Basic
A controlled value with min/max and Sundays disabled. The clear button appears as soon as a date is selected.
Locale and week start
The trigger and the calendar share the locale; weekStartsOn controls the first grid column.
States
Empty, required, disabled and read-only fields. Read-only keeps the value focusable without opening the calendar.
Usage
value/onChange uses Date or null. Set locale and weekStartsOn deliberately; min and max are inclusive calendar-day limits.
Use name for the hidden form input, and use clearable to control clearing. Treat the chosen value as a calendar day: converting local midnight to UTC can change its date.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluDatePickerProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
id | string | undefined | — | Id of the trigger button. Generated when omitted. |
name | string | undefined | — | Name of the hidden input submitted with the form. |
value | Date | null | undefined | — | Controlled value. Omit to let the picker own it; `null` is empty. |
defaultValue | Date | null | undefined | null | Initial value when uncontrolled. |
onChange | ((value: Date | null) => void) | undefined | — | Called with the selected day, or `null` when cleared. |
placeholder | string | undefined | "Select date" | Text shown while no date is selected. Defaults to "Select date". |
label | string | undefined | — | Visible label, also used as the trigger's accessible name. |
min | Date | undefined | — | Earliest selectable day, inclusive. |
max | Date | undefined | — | Latest selectable day, inclusive. |
disabledDates | PimoluDisabledDates | undefined | — | Dates that cannot be selected, as a list or a predicate. |
disabled | boolean | undefined | false | Never open the calendar. |
readOnly | boolean | undefined | false | Keep the value visible and focusable but not editable. |
required | boolean | undefined | false | Marks the field as required and shows the required marker. |
clearable | boolean | undefined | true | Show the clear button when a date is selected. Defaults to true. |
fullWidth | boolean | undefined | false | Stretch the field to the parent width. |
locale | string | undefined | "en-US" | BCP 47 locale for display and calendar labels. Defaults to "en-US". |
weekStartsOn | 0 | 1 | undefined | 0 | First day of the week: 0 = Sunday, 1 = Monday. Defaults to 0. |
clearLabel | string | undefined | — | Accessible label for the clear button. |
className | string | undefined | — | Class applied to the outer field. |
aria-label | string | undefined | — | Accessible name for the trigger when no visible label is used. |
idstring | undefinedNo default extracted.
Id of the trigger button. Generated when omitted.
namestring | undefinedNo default extracted.
Name of the hidden input submitted with the form.
valueDate | null | undefinedNo default extracted.
Controlled value. Omit to let the picker own it; `null` is empty.
defaultValueDate | null | undefinedDefault: null
Initial value when uncontrolled.
onChange((value: Date | null) => void) | undefinedNo default extracted.
Called with the selected day, or `null` when cleared.
placeholderstring | undefinedDefault: "Select date"
Text shown while no date is selected. Defaults to "Select date".
labelstring | undefinedNo default extracted.
Visible label, also used as the trigger's accessible name.
minDate | undefinedNo default extracted.
Earliest selectable day, inclusive.
maxDate | undefinedNo default extracted.
Latest selectable day, inclusive.
disabledDatesPimoluDisabledDates | undefinedNo default extracted.
Dates that cannot be selected, as a list or a predicate.
disabledboolean | undefinedDefault: false
Never open the calendar.
readOnlyboolean | undefinedDefault: false
Keep the value visible and focusable but not editable.
requiredboolean | undefinedDefault: false
Marks the field as required and shows the required marker.
clearableboolean | undefinedDefault: true
Show the clear button when a date is selected. Defaults to true.
fullWidthboolean | undefinedDefault: false
Stretch the field to the parent width.
localestring | undefinedDefault: "en-US"
BCP 47 locale for display and calendar labels. Defaults to "en-US".
weekStartsOn0 | 1 | undefinedDefault: 0
First day of the week: 0 = Sunday, 1 = Monday. Defaults to 0.
clearLabelstring | undefinedNo default extracted.
Accessible label for the clear button.
classNamestring | undefinedNo default extracted.
Class applied to the outer field.
aria-labelstring | undefinedNo default extracted.
Accessible name for the trigger when no visible label is used.
Accessibility
- Provide label or aria-label; retain an explicit name for the clear action.
- Test calendar arrows, opening, closing and focus return. Communicate unavailable dates and validation in text.