Skip to content
WunderUI

Date Picker

Free

A 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-picker

Playground

Installation

bash
npx wunderui-cli add date-picker

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Calendar for a month shown on the page, for example next to a schedule
  • Input for free text that is not a date
  • Select for a choice from a short fixed list, such as a month or a year

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

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

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.

TaborShiftTab
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

Mo
Tu
We
Th
Fr
Sa
Su

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).

  • Optional

    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.

  • 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.

  • 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 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.

PropTypeDefaultDescription
mode"single"— picks one date and picks a start and an end. It also decides the shape of : a , or .
valueDate—The date or the range, to control it. Update it in .
defaultValueDate—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.
labelstring—The visible label of a . Without it the field is named or for screen readers.
helperTextstring | false—The line under a . It defaults to the format hint, and hides it.
errorstring—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).
typeableboolean—Turns a into a text box with a calendar button, so the date can be typed.
defaultTextstring—The text a typeable field starts with, for example a draft that is not a date yet. It is checked on mount.
todayDate—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.
presetsboolean | DatePreset[]—Range only. shows the eight built-in quick ranges at the left; an array of shows your own, where gets and returns .
numberOfMonths1 | 2—Range only. or months side by side. It defaults to 2, and to 1 for presets below 830 px.
openboolean—Whether the popover is open, to control it.
defaultOpenboolean—Whether the popover starts open when is not set.
onOpenChange(open) => void—Called with the new open state when the popover opens or closes.
placeholderstring—The text shown while empty. It defaults to or for a button, and to the format for a field.
minDate—The earliest day that can be picked or typed.
maxDate—The latest day that can be picked or typed.
disabledCalendarProps["disabled"]—Days that cannot be picked or typed: a list of dates, or a function that returns true for a blocked day.
classNamestring—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).

PropTypeDefaultDescription
mode"single" | "range""single" or .
valueDate | 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 .
presetsboolean | DatePreset[]—Range only. or an array of presets, as on DatePicker.
numberOfMonths1 | 2—Range only. or months side by side. It defaults to 2.
stackedboolean—Stacks the two months of a range below each other, for a narrow container.
minDate—The earliest day that can be picked.
maxDate—The latest day that can be picked.
disabledCalendarProps["disabled"]—Days that cannot be picked: a list of dates, or a function.
todayDate—Overrides the date of today.
defaultMonthDate—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.
errorstring—An error message for the summary line. It keeps Apply off.
surfaceboolean—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.
classNamestring—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.

PropTypeDefaultDescription
mode"range" | "single""single" or , which decides the placeholder and the helper line.
valueDate | DateRange—The date or range to show.
labelstring—The visible label.
helperTextstring | false—The line under the field; hides it.
errorstring—An error message under the field.
fieldState"default" | "disabled" | "readonly""default", or .
placeholderstring—The text shown while empty.
openboolean—Draws the field as open, with its focus ring.
idstring—The id the label and the value are tied to.
classNamestring—Extra classes for the field.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("date-picker")
Installnpx wunderui-cli add date-picker

The full library index for assistants is at /llms.txt.