# DatePicker

Source: https://payloadcms.com/docs/beta/ui-components/date-picker

The `DatePicker` component wraps `react-datepicker` with Payload's styles, localization, and date and time display options.

## Import

Inside a Payload Admin Panel Custom Component:

```tsx
import { DatePicker } from '@payloadcms/ui'
```

## Basic usage

**Implementation**

```tsx
const [value, setValue] = useState<Date>()

<label htmlFor="publish-date-input">Publish date</label>
<DatePicker
  onChange={setValue}
  overrides={{ id: 'publish-date-input' }}
  placeholder="Select a date"
  value={value}
/>
```

**Styling**

Override field tokens on DatePicker for the input, then scope calendar tokens to react-datepicker for the open calendar surface and selected date.

```css
@layer payload {
  .date-time-picker {
    --field-color-bg: #f8f7fc;
    --field-color-border: #8f87bd;
    --field-color-placeholder: #625d82;
    --field-border-radius: 0.5rem;
  }

  .react-datepicker {
    --color-bg: #ffffff;
    --color-bg-selected-strong: #6d5dfc;
    --color-text-onselected-strong: #ffffff;
  }
}
```

- `--field-color-bg`: Input background.
- `--field-color-border`: Input border.
- `--field-color-placeholder`: Placeholder text color.
- `--field-border-radius`: Input corner radius.
- `--color-bg-selected-strong`: Selected date background.

Pair the picker with a visible label. `id` is applied to the picker's wrapper element, not to the underlying input, so pass the input ID through `overrides` and point the label's `htmlFor` at that value:

```tsx
<label htmlFor="publish-date-input">Publish date</label>
<DatePicker
  onChange={setValue}
  overrides={{ id: 'publish-date-input' }}
  value={value}
/>
```

The Admin Panel supplies the translation context that DatePicker uses for its calendar labels.

## Picker appearances

Use `pickerAppearance` to choose between a date, date and time, day, month, or time input. Payload selects a matching display format when `displayFormat` is not provided.

| Appearance   | Input                  |
| ------------ | ---------------------- |
| `default`    | Calendar date          |
| `dayAndTime` | Calendar date and time |
| `dayOnly`    | Day and month          |
| `monthOnly`  | Month                  |
| `timeOnly`   | Time                   |

## Common props

These are the props most commonly used with this component. See its exported types in `@payloadcms/ui` for the complete list.

| Prop               | Type                                                                  | Default     | Description                                      |
| ------------------ | --------------------------------------------------------------------- | ----------- | ------------------------------------------------ |
| `id`               | `string`                                                              | —           | Sets the ID of the picker's wrapper element.     |
| `value`            | `Date \| string`                                                      | —           | Selected date or date string.                    |
| `onChange`         | `(value: Date) => void`                                               | —           | Runs when the selected value changes.            |
| `placeholder`      | `string`                                                              | —           | Displays text when no value is selected.         |
| `pickerAppearance` | `'default' \| 'dayAndTime' \| 'dayOnly' \| 'monthOnly' \| 'timeOnly'` | `'default'` | Selects the date and time controls shown.        |
| `displayFormat`    | `string`                                                              | Automatic   | Overrides the date-fns display format.           |
| `minDate`          | `Date`                                                                | —           | Sets the earliest selectable date.               |
| `maxDate`          | `Date`                                                                | —           | Sets the latest selectable date.                 |
| `monthsToShow`     | `1 \| 2`                                                              | `1`         | Sets the number of visible calendar months.      |
| `timeIntervals`    | `number`                                                              | `30`        | Sets the number of minutes between time options. |
| `readOnly`         | `boolean`                                                             | `false`     | Prevents the value from being changed.           |
| `overrides`        | `ReactDatePickerProps`                                                | —           | Passes supported options to `react-datepicker`.  |