Date Picker
FreeA field or button that opens a calendar in a popover, to pick one date or a range, with presets, limits and typing.
npx wunderui-cli add date-pickerPlayground
Installation
npx wunderui-cli add date-pickerWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
DatePicker,
DatePickerField,
DatePickerFooter,
DatePickerPanel,
} from "@/components/wunderui/date-picker"
import type {
DatePickerFieldProps,
DatePickerFooterProps,
DatePickerPanelProps,
DatePickerProps,
} from "@/components/wunderui/date-picker"Then use it:
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.
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
Layout
A range shows two months side by side. Add presets for quick ranges at the left, like Last 7 days, and below 830 px the presets show one month.
Confirmation
By default the choice is a draft until Apply, and Cancel or closing drops it. For a single date, instant confirmation commits on the click and closes the popover.
Limits
Minimum, maximum and disabled days go straight to the calendar. Blocked days are dimmed, and typed dates outside the limits are rejected with a message.
Field states
The label is always visible. An empty field keeps the format hint, an unfinished range explains what is missing, and an invalid entry shows its message below.
Format: MM/DD/YYYY
Format: MM/DD/YYYY
Format: MM/DD/YYYY
Format: MM/DD/YYYY
Format: MM/DD/YYYY
Format: MM/DD/YYYY – MM/DD/YYYY
Format: MM/DD/YYYY – MM/DD/YYYY
Select an end date to finish the range.
The end date must be after the start date.
Format: MM/DD/YYYY – MM/DD/YYYY
Format: MM/DD/YYYY – MM/DD/YYYY
Footer
DatePickerFooter is the summary line with Cancel and Apply. It says what is missing, explains an error, or shows the range with its number of days.
No dates selected
Nov 22, 2026 – select an end date
The end date must be after the start date.
Nov 22 – Dec 5, 2026 · 14 days
Keyboard interactions
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.
- TaborShift+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.
- EnterorSpace
- 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 and , 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.
- ArrowLeftorArrowRightorArrowUporArrowDownorPageUporPageDown
- In the calendar: move by day, week and month. See the Calendar page for Home, End and the year keys.
Behavior and motion
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
The figure shows the panel that the popover holds: presets, a calendar, the summary and the buttons. The trigger is the button or field that opens it.
November 2026
Nov 3 – Nov 9, 2026 · 7 days
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.
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.
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).
- 1Optional
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.
- 2
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.
- 3
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.
- 4
Cancel closes the popover and drops the draft. Apply commits it and closes, and stays disabled while nothing valid can be committed.
- Optional
The summary line with Cancel and Apply, as its own part for panels you compose yourself.
- Optional
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.
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.
- Do
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.
- Do
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.
- Do
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.
- Do
Limit the choice with min, max and disabled days. They block days in the calendar and are enforced when a date is typed.
- Do
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
Don't use a Date Picker for a month shown next to your content. Use Calendar, which has no popover.
- Don’t
Don't leave the label out of a field. The format hint disappears once a date is chosen, but the label stays.
API reference
One table per part. Each is a plain component, so the tables list every prop, and most DatePicker limits are passed on to the Calendar.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | "single" | — | picks one date and picks a start and an end. It also decides the shape of : a , or . |
| value | Date | — | The date or the range, to control it. Update it in . |
| defaultValue | Date | — | The date or range to start with when the picker keeps its own state. |
| onValueChange | (date) => void | — | Called with the committed date or range: on Apply, on a click in mode, or when a typed entry is accepted. It is called with when a typed field is cleared. |
| appearance | "button" | "field" | — | (the default) is a plain button; is a form field with a label, a format hint and an error line. |
| label | string | — | The visible label of a . Without it the field is named or for screen readers. |
| helperText | string | false | — | The line under a . It defaults to the format hint, and hides it. |
| error | string | — | An error message for a . It turns the field red, shows the message under it and keeps Apply off. |
| fieldState | "default" | "disabled" | "readonly" | — | , (dimmed, does not open) or (focusable, shows the value, does not open). |
| typeable | boolean | — | Turns a into a text box with a calendar button, so the date can be typed. |
| defaultText | string | — | The text a typeable field starts with, for example a draft that is not a date yet. It is checked on mount. |
| today | Date | — | Overrides the date of today, which defaults to . Use it for demos and tests. |
| confirmation | "apply" | "instant" | — | (the default) keeps a draft until Apply; commits a single date on the click and leaves the footer out. |
| unit | "days" | "nights" | — | (the default) or : what the range length in the summary is counted in. |
| presets | boolean | DatePreset[] | — | Range only. shows the eight built-in quick ranges at the left; an array of shows your own, where gets and returns . |
| numberOfMonths | 1 | 2 | — | Range only. or months side by side. It defaults to 2, and to 1 for presets below 830 px. |
| open | boolean | — | Whether the popover is open, to control it. |
| defaultOpen | boolean | — | Whether the popover starts open when is not set. |
| onOpenChange | (open) => void | — | Called with the new open state when the popover opens or closes. |
| placeholder | string | — | The text shown while empty. It defaults to or for a button, and to the format for a field. |
| min | Date | — | The earliest day that can be picked or typed. |
| max | Date | — | The latest day that can be picked or typed. |
| disabled | CalendarProps["disabled"] | — | Days that cannot be picked or typed: a list of dates, or a function that returns true for a blocked day. |
| className | string | — | Extra classes for the trigger. |
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).
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | "single" | "range" | "single" | or . |
| value | Date | DateRange | — | The date or range the draft starts from. |
| onApply | (value) => void | — | Called with the draft when Apply is pressed, and in mode with the day that was clicked. |
| onCancel | () => void | — | Called when Cancel is pressed. |
| confirmation | "apply" | "instant" | "apply" | or . |
| presets | boolean | DatePreset[] | — | Range only. or an array of presets, as on DatePicker. |
| numberOfMonths | 1 | 2 | — | Range only. or months side by side. It defaults to 2. |
| stacked | boolean | — | Stacks the two months of a range below each other, for a narrow container. |
| min | Date | — | The earliest day that can be picked. |
| max | Date | — | The latest day that can be picked. |
| disabled | CalendarProps["disabled"] | — | Days that cannot be picked: a list of dates, or a function. |
| today | Date | — | Overrides the date of today. |
| defaultMonth | Date | — | The month the first calendar starts on. It defaults to the month of the draft, else today. |
| unit | "days" | "nights" | "days" | or , for the length in the summary. |
| error | string | — | An error message for the summary line. It keeps Apply off. |
| surface | boolean | — | Draws a border, the popover surface and a shadow, for a panel that sits on the page. |
| header | "label" | "month-year" | "label" | or , the header of the calendars. |
| className | string | — | Extra classes for the panel. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | "range" | "single" | "single" | or , which decides the placeholder and the helper line. |
| value | Date | DateRange | — | The date or range to show. |
| label | string | — | The visible label. |
| helperText | string | false | — | The line under the field; hides it. |
| error | string | — | An error message under the field. |
| fieldState | "default" | "disabled" | "readonly" | "default" | , or . |
| placeholder | string | — | The text shown while empty. |
| open | boolean | — | Draws the field as open, with its focus ring. |
| id | string | — | The id the label and the value are tied to. |
| className | string | — | Extra classes for the field. |
The summary line with Cancel and Apply, as its own part for panels you compose yourself.
| Prop | Type | Default | Description |
|---|---|---|---|
| summary required | ReactNode | — | The text at the left: what is missing, an error or the choice. |
| invalid | boolean | — | Draws the summary as an error. |
| applyDisabled | boolean | — | Disables the Apply button. |
| onCancel | () => void | — | Called when Cancel is pressed. |
| onApply | () => void | — | Called when Apply is pressed. |
| className | string | — | Extra classes for the footer row. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("date-picker")npx wunderui-cli add date-pickerThe full library index for assistants is at /llms.txt.