Date Picker

Collapsible date field with a portaled Calendar panel, locale-aware trigger formatting, and spring open motion.

Installation

npx shadcn@latest add @iconiq/date-picker

File Structure

Usage

"use client";

import { useState } from "react";

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

export function DatePickerPreview() {
  const [value, setValue] = useState<Date | null>(new Date());

  return (
    <DatePicker onChange={setValue} value={value} />
  );
}

Props

Props
Description

DatePicker

value

Controlled selected date. When provided, the trigger and embedded Calendar both reflect this value.

Type Date | null

defaultValue

Initial selected date for uncontrolled usage when `value` is omitted.

Type Date | null·Default null

placeholder

Copy shown in the trigger when no date is selected.

Type string·Default Select a date

onChange

Called when the user picks or clears a date from the embedded Calendar or clear control.

Type (date: Date | null) => void

className

Optional class names applied to the outer wrapper.

Type string

defaultOpen

Whether the Calendar panel starts expanded on first render.

Type boolean·Default false

open

Controlled open state for the Calendar panel. Pair with `onOpenChange`.

Type boolean

onOpenChange

Called when the panel opens or closes from the trigger, selection, Escape, or outside click.

Type (open: boolean) => void

disabled

Disables the trigger and prevents the panel from opening.

Type boolean·Default false

clearable

Shows a clear button when a date is selected so users can reset to `null`.

Type boolean·Default false

closeOnSelect

Whether picking a date closes the panel automatically.

Type boolean·Default true

dateFormat

date-fns format string for the trigger label. Uses `calendarProps.locale` when provided.

Type string·Default EEE, MMM d, yyyy

name

Optional form field name. Renders a hidden input with the selected ISO date.

Type string

id

Optional id applied to the trigger button.

Type string

aria-invalid

Marks the trigger as invalid for assistive tech and applies error styling.

Type boolean

side

Preferred panel side relative to the trigger. Flips when there is not enough space.

Type "top" | "bottom"·Default bottom

align

Horizontal alignment of the portaled panel to the trigger.

Type "start" | "end"·Default start

calendarProps

Props forwarded to the embedded Calendar, such as size, locale, disabled, bounds, modifiers, weekStartsOn, minYear, and maxYear. Range mode is not supported on DatePicker.

Type Omit<CalendarProps, 'selected' | 'defaultSelected' | 'onSelect' | 'month' | 'onMonthChange' | 'mode' | 'range' | 'defaultRange' | 'onRangeSelect'>

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react/input, motion, lucide-react, date-fns.

Registry dependency: calendar. Install date-picker together with the shared Calendar component.

The generated registry file is /r/date-picker.json.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.