# DatePicker

> Typed date field plus a calendar popover.

Source: https://ui.jcsoftdev.com/docs/components/date-picker

Typed date field plus a calendar popover. The value is an ISO "YYYY-MM-DD" string end to end,
so it never shifts with the time zone. The person types in the locale's order ("07/09/2026" in
es-PE) or picks from the calendar; Alt+ArrowDown opens it from the keyboard.

## Import

```ts
import { DatePicker } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/date-picker`.

## Usage

```tsx
<DatePicker aria-label="Start date" defaultValue="2026-09-07" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Selected date as "YYYY-MM-DD" (controlled); `""` means none. Never converted through a time zone. |
| `defaultValue` | `string` | `""` |  |
| `onValueChange` | `((value: string) => void)` |  | Called with a valid "YYYY-MM-DD" date, or `""` when the field is cleared. |
| `min` | `string` |  | Earliest allowed date, "YYYY-MM-DD". |
| `max` | `string` |  | Latest allowed date, "YYYY-MM-DD". |
| `isDateDisabled` | `((date: string) => boolean)` |  | Extra dates that cannot be picked or typed (holidays, taken days). |
| `locale` | `string` |  | BCP 47 locale for labels and the typed format. Defaults to the `locale` UI string (es-PE: dd/mm/aaaa). |
| `weekStartsOn` | `0 \| 2 \| 1 \| 4 \| 3 \| 5 \| 6` |  | First day of the week in the calendar, 0 (Sunday) to 6. Defaults from the locale (es-PE: Monday). |
| `size` | `"sm" \| "md"` | `"md"` | `sm` is 30px and `md` (default) 38px, the heights of `Button` and `Input` of the same size. |
| `clearable` | `boolean` | `true` | Shows a button that clears the date. Default `true`. |
| `clearLabel` | `string` |  |  |
| `name` | `string` |  | Submits the "YYYY-MM-DD" value with a surrounding `<form>` through a hidden input. |
| `invalid` | `boolean` |  |  |
| `container` | `HTMLElement \| null` |  | Portal target for the calendar popover. Defaults to `document.body`. |
| `material` | `"solid" \| "glass" \| "glass-clear" \| "liquid" \| "liquid-clear"` |  | Popover surface material; see `PopoverContent`. |
| `classNames` | `Partial<Record<DatePickerPart, string>>` |  | Per-part classes merged with `cn`; consumer classes win. `className` still targets the input and is merged last. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-datepicker--default)
- [English Writes Month First](/storybook/?path=/story/forms-datepicker--english-writes-month-first)
- [Typing Commits Only Real Dates](/storybook/?path=/story/forms-datepicker--typing-commits-only-real-dates)
- [Pick From Calendar With Keyboard](/storybook/?path=/story/forms-datepicker--pick-from-calendar-with-keyboard)
- [Escape Closes Without Change](/storybook/?path=/story/forms-datepicker--escape-closes-without-change)
- [Min Max And Disabled Dates](/storybook/?path=/story/forms-datepicker--min-max-and-disabled-dates)
- [Clearable](/storybook/?path=/story/forms-datepicker--clearable)
- [Inside Field And Form](/storybook/?path=/story/forms-datepicker--inside-field-and-form)
- [Controlled](/storybook/?path=/story/forms-datepicker--controlled)
- [Disabled](/storybook/?path=/story/forms-datepicker--disabled)
- [Date Time](/storybook/?path=/story/forms-datepicker--date-time)
- [Date Time Inside Field](/storybook/?path=/story/forms-datepicker--date-time-inside-field)

## Source

`packages/ui/src/forms/date-picker/date-picker.tsx`