# Date Picker

- Page: <https://kznlabs.github.io/labsUI/components/date-picker>

## Date Picker (`date-picker`, component)

Field-styled button that opens a Calendar in a Popover, focused on the picked day. Single or range, presets such as Last 7 days, closes once the pick is complete, and submits ISO dates through a hidden input. Works inside Field.

- Install: `npx @kznlabs/labsui add date-picker`
- Docs: <https://kznlabs.github.io/labsUI/components/date-picker>
- Brings: button, button-variants, calendar, field, input, label, platform, popover, use-anchor, use-controllable-state, use-dismiss, utils
- npm: clsx@^2.1.1, lucide-react@1.63.0, motion@14.7.1, tailwind-merge@^3.7.0

### API

- `<DatePicker>`: Field-styled button that opens a Calendar in a Popover, focused on the picked day. A single
date closes on pick; a range closes once both ends are set. Optional presets, form-ready.
  - `aria-describedby?: string`: Ids of hint or error text; Field fills it in.
  - `aria-invalid?: boolean`: Error styling; Field sets it from `error`.
  - `aria-label?: string`: Accessible name when there is no visible label.
  - `defaultValue?: Date | DateRange | null`: Day or range at first render (uncontrolled).
  - `disabled?: boolean`: Blocks opening.
  - `id?: string`: Pair with <Label htmlFor>, or let <Field> fill it in.
  - `isDisabled?: (date: Date) => boolean`: Extra rule, e.g. weekends off. Client-only (a function).
  - `locale?: string`: BCP 47 locale for the button text and the calendar.
  - `max?: Date`: Latest selectable day.
  - `min?: Date`: Earliest selectable day.
  - `mode?: "single" | "range"`: "single": pick one day. "range": pick a start, then an end.
  - `name?: string`: Submits ISO through a hidden input: `2026-10-21`, or `2026-10-03/2026-10-09` for a range.
  - `onValueChange?: ((date: Date) => void) | ((range: DateRange) => void)`: Called with the picked day, or with the range once both ends are set.
  - `placeholder?: string`: Button text when nothing is picked.
  - `presets?: Preset<Date>[] | Preset<DateRange>[]`: Shortcuts beside the grid, e.g. Today, or Last 7 days for a range. Readers reach for these first.
  - `required?: boolean`: Form submit needs a date.
  - `value?: Date | DateRange | null`: Controlled day, or `{ from, to }` in range mode; null = nothing picked.
  - `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6`: 0 is Sunday, 6 is Saturday. Default 1 (Monday, ISO).

- `type Preset = { label: string; value: Value }`

### Usage

```tsx
<Field label="Report period"><DatePicker mode="range" name="period" presets={[{ label: "Last 7 days", value: { from, to } }]} /></Field>
```

### Example: report-filters.tsx

```tsx
"use client";

import { DatePicker } from "@/components/ui/date-picker";
import { Field } from "@/components/ui/field";

const today = new Date();
const ago = (days: number) => new Date(today.getFullYear(), today.getMonth(), today.getDate() - days);

// Submits period=2026-10-03/2026-10-09 with the form.
export function ReportFilters() {
  return (
    <Field label="Report period">
      <DatePicker
        mode="range"
        name="period"
        max={today}
        presets={[
          { label: "Last 7 days", value: { from: ago(6), to: today } },
          { label: "Last 30 days", value: { from: ago(29), to: today } },
        ]}
      />
    </Field>
  );
}
```