# Date Picker

A Calendar inside a Popover, with Cancel/Apply actions.

- Category: Forms
- Page: https://wunderui.com/components/date-picker
- Tier: Free

## Install

```bash
npx wunderui-cli add date-picker
```

## Import

```tsx
import { DatePicker, DatePickerField, DatePickerFieldProps, DatePickerFooter, DatePickerFooterProps, DatePickerPanel, DatePickerPanelProps, DatePickerProps } from "@/components/wunderui/date-picker"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { DatePicker } from "@/components/ui/date-picker"

export function DueDate() {
  const [date, setDate] = useState<Date | undefined>()

  return <DatePicker value={date} onValueChange={setDate} />
}
```

Expected result: You see a button that says Pick a date. Press it, choose a day and press Apply: the button shows the date, for example Nov 12, 2026.

## Usage

```tsx
import { useState } from "react"
import { DatePicker } from "@/components/ui/date-picker"

export function Example() {
  const [value, setValue] = useState<Date | undefined>(new Date(2026, 10, 12))

  return (
    <DatePicker value={value} onValueChange={setValue} />
  )
}
```

## When to use

### Use Date Picker for

- One date in a form, such as a due date, a delivery date or a date of birth
- A date range that filters a report, with quick ranges such as Last 30 days
- A date with limits, such as weekdays only or the next three months

### Use something else

- [Calendar](https://wunderui.com/components/calendar) for a month shown on the page, for example next to a schedule
- [Input](https://wunderui.com/components/input) for free text that is not a date
- [Select](https://wunderui.com/components/select) for a choice from a short fixed list, such as a month or a year

## Keyboard

The trigger is a native button or text field. The popover is not modal: Tab moves through its presets, calendar and buttons, and Escape closes it.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the trigger. In a typeable field it goes to the calendar icon in front of the text first (the button that opens the calendar), then into the text. Inside the open popover it moves through the presets, the calendar and the footer buttons. |
| `Enter` or `Space` | On the trigger or the calendar button: opens the popover. On a day: picks it. On Cancel or Apply: runs it. |
| `Enter` | In a typeable field: commits the typed date. A text that is not a date, or lies outside `min` and `max`, shows an error and keeps the old value. Leaving the field commits too. |
| `Escape` | Closes the popover, drops the draft and returns focus to the trigger. |
| `ArrowLeft` or `ArrowRight` or `ArrowUp` or `ArrowDown` or `PageUp` or `PageDown` | In the calendar: move by day, week and month. See the Calendar page for Home, End and the year keys. |

## Behavior

What the picker does with state, drafts, typing, limits and motion.

- **Controlled or not:** Pass a value and a change handler to hold the date or range, and an open state to hold the popover. Without them the picker keeps its own state, starting from the defaults you give.
- **Draft and commit:** By default the days you click are a draft. Apply commits it and closes the popover, while Cancel, Escape or a click outside drops it, and it reopens from the committed value.
- **Instant:** With instant confirmation a single date commits on the click and closes the popover, with no footer. It does not apply to a range.
- **Range:** The first click sets the start, the second the end, and a click before the start swaps them. A range without an end is incomplete, so Apply stays off, and an end before the start is an error.
- **Typing:** A typeable field parses MM/DD/YYYY and dates like Nov 12, 2026, and for a range two dates joined by a dash. It commits on Enter or blur, and a bad entry shows an error and keeps the last good value.
- **Limits:** Min, max and disabled days block days in the calendar, dim presets that fall outside, and reject typed dates.
- **Presets:** A preset fills the draft and moves the calendar to its start. The preset that matches the draft shows as selected.
- **Narrow screens:** Below 830 px a range with presets shows one month, and below 650 px a range without presets stacks its two months. There is no separate mobile version.
- **Focus:** The popover sits below the trigger, or below the text box of a typeable field. Closing it returns focus to the trigger.
- **Motion:** The popover fades and scales in, and out a step faster. The calendar and buttons inside change colour on the fast duration.
- **Reduced motion:** With reduced motion the popover keeps its fade and drops the scale. Colour changes on days and buttons are not movement and stay.

## Anatomy

- `DatePicker`: The trigger and the popover in one component. It looks like a plain button or, as a field, adds a label, a format hint and an error line, and it picks a single date or a range.
- `Trigger`: The element that opens the popover: a button, a field, or a text field you can type in. It shows Pick a date or the format hint while empty, then the chosen date or range.
- `DatePickerPanel`: The popover content: calendars, presets and footer. A range shows two months side by side, a single date one, and the popover is as wide as its content (312 px for one month).
- `Presets`: A column of quick ranges at the left, such as Last 7 days. Use the eight built-in ones or your own; choosing one fills the draft and Apply still confirms.
- `Calendar`: A medium Calendar with its own header and arrows: two calendars for a range, one for a single date. See the Calendar page for its keys and states.
- `Summary`: The line at the left of the footer. It says what is missing, explains an error, or shows the choice, with the length of a range in days or nights.
- `Cancel and Apply`: Cancel closes the popover and drops the draft. Apply commits it and closes, and stays disabled while nothing valid can be committed.
- `DatePickerField`: The closed field alone, without a popover, with its label and helper line. It is what the picker draws as a field, and is useful next to an inline panel.
- `DatePickerFooter`: The summary line with Cancel and Apply, as its own part for panels you compose yourself.

## Best practices

### Do

- Use the default button for a filter in a toolbar, and the field in a form, where it needs a label, a hint and an error line.
- Let people type dates far in the past or future, such as a date of birth. Typing beats paging, and the field takes MM/DD/YYYY or a written date like Nov 12, 2026.
- Use range mode with presets for reporting, where people usually want Last 7 days or Month to date. The picker shows one month below 830 px on its own.
- Use instant confirmation for a single date that is easy to change, such as a due date. Keep Apply and Cancel for ranges and for dates that trigger work, such as a booking.
- Limit the choice with min, max and disabled days. They block days in the calendar and are enforced when a date is typed.
- Say what an unfinished or invalid range needs. The field shows Select an end date to finish the range, or the error, and Apply stays off until the range is valid.

### Don't

- Don't use instant confirmation with a range. Without the footer there is nothing to commit it.
- Don't use a Date Picker for a month shown next to your content. Use Calendar, which has no popover.
- Don't leave the label out of a field. The format hint disappears once a date is chosen, but the label stays.

## API reference

### DatePicker

| Prop | Type | Default | Description |
|---|---|---|---|
| appearance | "button" \| "field" |  | `button` (the default) is a plain button; `field` is a form field with a label, a format hint and an error line. |
| className | string |  | Extra classes for the trigger. |
| confirmation | "apply" \| "instant" |  | `apply` (the default) keeps a draft until Apply; `instant` commits a single date on the click and leaves the footer out. |
| defaultOpen | boolean |  | Whether the popover starts open when `open` is not set. |
| defaultText | string |  | The text a typeable field starts with, for example a draft that is not a date yet. It is checked on mount. |
| defaultValue | Date |  | The date or range to start with when the picker keeps its own state. |
| disabled | CalendarProps["disabled"] |  | Days that cannot be picked or typed: a list of dates, or a function that returns true for a blocked day. |
| error | string |  | An error message for a `field`. It turns the field red, shows the message under it and keeps Apply off. |
| fieldState | "default" \| "disabled" \| "readonly" |  | `default`, `disabled` (dimmed, does not open) or `readonly` (focusable, shows the value, does not open). |
| helperText | string \| false |  | The line under a `field`. It defaults to the format hint, and `false` hides it. |
| label | string |  | The visible label of a `field`. Without it the field is named `Date` or `Date range` for screen readers. |
| max | Date |  | The latest day that can be picked or typed. |
| min | Date |  | The earliest day that can be picked or typed. |
| mode | "single" |  | `single` picks one date and `range` picks a start and an end. It also decides the shape of `value`: a `Date`, or `{ from, to }`. |
| numberOfMonths | 1 \| 2 |  | Range only. `1` or `2` months side by side. It defaults to 2, and to 1 for presets below 830 px. |
| onOpenChange | (open: boolean) => void |  | Called with the new open state when the popover opens or closes. |
| onValueChange | (date: Date \| undefined) => void |  | Called with the committed date or range: on Apply, on a click in `instant` mode, or when a typed entry is accepted. It is called with `undefined` when a typed field is cleared. |
| open | boolean |  | Whether the popover is open, to control it. |
| placeholder | string |  | The text shown while empty. It defaults to `Pick a date` or `Pick a date range` for a button, and to the format for a field. |
| presets | boolean \| DatePreset[] |  | Range only. `true` shows the eight built-in quick ranges at the left; an array of `{ label, range }` shows your own, where `range` gets `{ today, min }` and returns `{ from, to }`. |
| today | Date |  | Overrides the date of today, which defaults to `new Date()`. Use it for demos and tests. |
| typeable | boolean |  | Turns a `field` into a text box with a calendar button, so the date can be typed. |
| unit | "days" \| "nights" |  | `days` (the default) or `nights`: what the range length in the summary is counted in. |
| value | Date |  | The date or the range, to control it. Update it in `onValueChange`. |

### DatePickerField

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the field. |
| error | string |  | An error message under the field. |
| fieldState | "default" \| "disabled" \| "readonly" | "default" | `default`, `disabled` or `readonly`. |
| helperText | string \| false |  | The line under the field; `false` hides it. |
| id | string |  | The id the label and the value are tied to. |
| label | string |  | The visible label. |
| mode | "range" \| "single" | "single" | `single` or `range`, which decides the placeholder and the helper line. |
| open | boolean |  | Draws the field as open, with its focus ring. |
| placeholder | string |  | The text shown while empty. |
| value | Date \| DateRange |  | The date or range to show. |

### DatePickerFooter

| Prop | Type | Default | Description |
|---|---|---|---|
| summary* | React.ReactNode |  | The text at the left: what is missing, an error or the choice. |
| applyDisabled | boolean |  | Disables the Apply button. |
| className | string |  | Extra classes for the footer row. |
| invalid | boolean |  | Draws the summary as an error. |
| onApply | () => void |  | Called when Apply is pressed. |
| onCancel | () => void |  | Called when Cancel is pressed. |

### DatePickerPanel

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the panel. |
| confirmation | "apply" \| "instant" | "apply" | `apply` or `instant`. |
| defaultMonth | Date |  | The month the first calendar starts on. It defaults to the month of the draft, else today. |
| disabled | CalendarProps["disabled"] |  | Days that cannot be picked: a list of dates, or a function. |
| error | string |  | An error message for the summary line. It keeps Apply off. |
| header | "label" \| "month-year" | "label" | `label` or `month-year`, the header of the calendars. |
| max | Date |  | The latest day that can be picked. |
| min | Date |  | The earliest day that can be picked. |
| mode | "single" \| "range" | "single" | `single` or `range`. |
| numberOfMonths | 1 \| 2 |  | Range only. `1` or `2` months side by side. It defaults to 2. |
| onApply | (value: Date \| DateRange \| undefined) => void |  | Called with the draft when Apply is pressed, and in `instant` mode with the day that was clicked. |
| onCancel | () => void |  | Called when Cancel is pressed. |
| presets | boolean \| DatePreset[] |  | Range only. `true` or an array of presets, as on DatePicker. |
| stacked | boolean |  | Stacks the two months of a range below each other, for a narrow container. |
| surface | boolean |  | Draws a border, the popover surface and a shadow, for a panel that sits on the page. |
| today | Date |  | Overrides the date of today. |
| unit | "days" \| "nights" | "days" | `days` or `nights`, for the length in the summary. |
| value | Date \| DateRange |  | The date or range the draft starts from. |

## Examples

### Layout: two months, quick ranges, or quick ranges with one month

```tsx
import { useState } from "react"
import { DatePicker } from "@/components/ui/date-picker"

export function Example() {
  const [value, setValue] = useState<{ from?: Date; to?: Date } | undefined>({ from: new Date(2026, 10, 12), to: new Date(2026, 10, 18) })

  return (
    <DatePicker mode="range" value={value} onValueChange={setValue} />
  )
}
```

### Confirmation: Apply and Cancel, or instant

```tsx
import { useState } from "react"
import { DatePicker } from "@/components/ui/date-picker"

export function Example() {
  const [value, setValue] = useState<Date | undefined>(new Date(2026, 10, 12))

  return (
    <DatePicker confirmation="apply" value={value} onValueChange={setValue} />
  )
}
```

### Limits: a window of days, or weekdays only

```tsx
import { useState } from "react"
import { DatePicker } from "@/components/ui/date-picker"

export function Example() {
  const [value, setValue] = useState<Date | undefined>(new Date(2026, 10, 12))

  return (
    <DatePicker
      appearance="field"
      label="Delivery date"
      min={new Date(2026, 10, 9)}
      max={new Date(2026, 11, 9)}
      value={value}
      onValueChange={setValue}
    />
  )
}
```

### Field states: empty, filled, incomplete, invalid, disabled and readonly

```tsx
import { DatePicker } from "@/components/ui/date-picker"

export function Example() {
  return (
    <DatePicker appearance="field" label="Date" />
  )
}
```

### Footer: what the summary line says

```tsx
import { DatePickerFooter } from "@/components/ui/date-picker"

export function Example() {
  return <DatePickerFooter summary="No dates selected" applyDisabled />
}
```

## In context

### Report header: a range that drives the figures below

The range sits at the top of the page. Choose a quick range or two days and Apply, and the revenue, orders and caption below follow.

```tsx
import { useState } from "react"
import { DatePicker } from "@/components/ui/date-picker"

const DAY = 86_400_000
const short = (day: Date) => day.toLocaleDateString("en-US", { month: "short", day: "numeric" })

export function Example() {
  const [range, setRange] = useState<{ from?: Date; to?: Date } | undefined>({
    from: new Date(2026, 10, 1),
    to: new Date(2026, 10, 7),
  })
  const days = range?.from && range.to ? Math.round((range.to.getTime() - range.from.getTime()) / DAY) + 1 : 0

  return (
    <div className="flex w-full max-w-xl flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <div className="flex items-center justify-between gap-3">
        <h3 className="text-base font-semibold text-foreground">Revenue</h3>
        <DatePicker mode="range" presets numberOfMonths={1} value={range} onValueChange={setRange} />
      </div>
      <div className="grid grid-cols-2 gap-4 border-t border-border pt-4">
        <div>
          <p className="text-sm text-text-secondary">Revenue</p>
          <p className="text-2xl font-semibold tabular-nums text-foreground">${(days * 3210).toLocaleString("en-US")}</p>
        </div>
        <div>
          <p className="text-sm text-text-secondary">Orders</p>
          <p className="text-2xl font-semibold tabular-nums text-foreground">{(days * 123).toLocaleString("en-US")}</p>
        </div>
      </div>
      <p className="text-xs text-text-tertiary">
        {range?.from && range.to ? `${short(range.from)} – ${short(range.to)}, ${range.to.getFullYear()} · ${days} days` : "Choose a range"}
      </p>
    </div>
  )
}
```

### Birth date in a sign-up form: typing first

Typing is the fastest way to a date far in the past, so the field is typeable and the calendar is the fallback. Days after today are blocked, and the button stays off until the date is valid.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { DatePicker } from "@/components/ui/date-picker"

export function Example() {
  const [birthday, setBirthday] = useState<Date | undefined>()

  return (
    <form className="flex w-full max-w-sm flex-col gap-4">
      <DatePicker
        appearance="field"
        typeable
        label="Date of birth"
        helperText="Format: MM/DD/YYYY. Type the date or pick it."
        max={new Date(2026, 10, 9)}
        value={birthday}
        onValueChange={setBirthday}
      />
      <Button variant="gradient" disabled={!birthday}>
        Create account
      </Button>
    </form>
  )
}
```

### Check-in and check-out: nights, with booked days blocked

The panel sits on the page instead of in a popover. Booked days are unavailable and the footer counts the stay in nights.

```tsx
import { useState } from "react"
import { DatePickerPanel } from "@/components/ui/date-picker"

const BOOKED = [new Date(2026, 10, 14), new Date(2026, 10, 15), new Date(2026, 10, 16)]

export function Example() {
  const [stay, setStay] = useState<{ from?: Date; to?: Date } | undefined>({
    from: new Date(2026, 10, 20),
    to: new Date(2026, 10, 24),
  })

  return (
    <DatePickerPanel
      mode="range"
      unit="nights"
      surface
      min={new Date(2026, 10, 9)}
      disabled={BOOKED}
      value={stay}
      onApply={(value) => setStay(value as { from?: Date; to?: Date } | undefined)}
    />
  )
}
```

## For AI agents

`get_component("date-picker")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
