---
title: Date Picker
description: A date picker component with range and presets.
icon: calendar-days
author:
  name: shadcn
  url: https://github.com/shadcn
search:
  keywords: [calendar input, datepicker]
mode: wide
---

<PoweredBy
  packages={[
    { name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/date-picker' },
    { name: 'Lucide', url: 'https://lucide.dev/' },
    { name: 'React Day Picker', url: 'https://daypicker.dev/' },
    { name: 'date-fns', url: 'https://date-fns.org/' },
    { name: 'chrono', url: 'https://github.com/wanasit/chrono' },
  ]}
/>

<ComponentPreview name="date-picker-demo" description="A date picker in a popover" />

## When to use

Use this decision tree to determine when to use the Date Picker component:

```mermaid
graph TD;
    A[❓ Need date input?] --> B{What type of date selection?};
    B --> C[✅ Single date selection];
    B --> D[✅ Date range selection];
    B --> E[⚠️ Time-only selection];
    B --> F[ℹ️ Date + time together];

    C --> G[❓ Input method preference?];
    D --> H[✅ Use date range variants];
    E --> I[⚠️ Use TimePicker instead];
    F --> J[✅ Use date-time variants];

    G --> K["✅ Calendar popup (recommended)"];
    G --> L[ℹ️ Text input with parsing];

    K --> M[❓ Mobile considerations?];
    L --> N[✅ Use natural language variant];
    H --> M;
    J --> M;

    M --> O[✅ Use drawer on mobile];
    M --> P[ℹ️ Popover only];

    O --> Q[❓ Need presets?];
    P --> Q;
    N --> Q;

    Q --> R["✅ Add preset options (Today, etc)"];
    Q --> S[ℹ️ Basic date picker];

    R --> T[❓ Form integration?];
    S --> T;

    T --> U[✅ Use with Form components];
    T --> V[ℹ️ Standalone implementation];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class C,D,H,J,K,N,O,R,U recommended;
    class E,I discouraged;
    class A,B,G,M,Q,T decision;
    class F,L,P,S,V neutral;
```

### Installation

The Date Picker is built using a composition of the `<Popover />` and the `<Calendar />` components.

See installation instructions for the [Popover](/docs/popover#installation) and the [Calendar](/docs/calendar#installation) components.

## Usage

```tsx expandable
'use client';

import * as React from 'react';
import { format } from 'date-fns';
import { Calendar as CalendarIcon } from 'lucide-react';

import { cn } from '@/registry/lib/utils';
import { Button } from '@/components/ui/button';
import { Calendar } from '@/components/ui/calendar';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';

export function DatePickerDemo() {
  const [date, setDate] = React.useState<Date>();

  return (
    <Popover>
      <PopoverTrigger
        render={
          <Button
            variant={'outline'}
            className={cn('w-[280px] justify-start text-left font-normal', !date && 'text-subtle')}
          >
            <CalendarIcon className="mr-2 h-4 w-4" />
            {date ? format(date, 'PPP') : <span>Pick a date</span>}
          </Button>
        }
      />
      <PopoverContent className="w-auto p-0">
        <Calendar mode="single" selected={date} onSelect={setDate} autoFocus />
      </PopoverContent>
    </Popover>
  );
}
```

See the [React DayPicker](https://daypicker.dev/) documentation for more information.

## Examples

### Date Picker

<ComponentPreview name="date-picker-demo" description="A date picker in a popover" />

### Date Picker Drawer

<ComponentPreview name="date-picker-drawer-demo" description="A date picker in a drawer" />

The drawer uses the existing embedded Calendar surface with spacing-scale11 cells: 44px targets in a 308px-wide
calendar, fitting a 320px viewport without the old viewport-derived clamp. Native date selection, month/year
controls and focus restoration remain unchanged.

### Date Picker With Form

<ComponentPreview name="date-picker-form-demo" description="A date picker with a form" />

### Date Picker Natural Language

<ComponentPreview
  name="date-picker-natural-language-demo"
  description="A date picker you can use with natural language"
/>

### Date Picker With Presets

<ComponentPreview name="date-picker-with-presets-demo" description="A date picker with preselectable presets" />

Today and Tomorrow resolve the current local date when activated, including after the example has remained open
across midnight. They add calendar days rather than fixed 24-hour intervals, preserving local dates across
daylight-saving changes.

### Date Picker With Range

<ComponentPreview name="date-picker-with-range-demo" description="A date picker with range" />

### Date Picker With Time Range

<ComponentPreview name="date-picker-with-time-range-demo" description="A date picker with time range" />

### Date Picker With Time

<ComponentPreview name="date-picker-with-time-demo" description="A date picker with time" />

### Date Range Picker With Time

<ComponentPreview name="date-range-picker-with-time-demo" description="A date range picker with time" />

## Credits

- We use [react-day-picker](https://daypicker.dev/) for the date picker.
- We use [chrono](https://github.com/wanasit/chrono) for the natural language functionality of the date picker.
- Date ranges use the existing [date-fns](https://date-fns.org/) dependency.
- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/date-picker) for the date picker style.