# Datepicker (w-datepicker)

## Description

A date picker allows the user to select a specific calendar date.

[Warp component reference](https://warp-ds.github.io/docs/components/date-picker/frameworks/elements)

## Usage

Datepicker lets users type or choose a calendar date.

Use `w-datepicker` when the user needs to provide one specific date, such as a travel date, appointment date, or deadline. The component is form-associated and submits an ISO date value.

### Basic Datepicker

```html
<w-datepicker label="Date" name="date"></w-datepicker>
```

Always provide a visible `label`.

### Value

Use `value` to set the selected date. The value should use `YYYY-MM-DD` format.

```html
<w-datepicker label="Start date" name="start-date" value="2026-06-15"></w-datepicker>
```

The same value is submitted with the form.

```html
<form>
  <w-datepicker label="Departure date" name="departure"></w-datepicker>
  <w-button type="submit">Search</w-button>
</form>
```

### Locale

Datepicker uses the `lang` attribute on the component, or the `lang` attribute on `<html>`, to choose locale-specific calendar labels and formatting.

```html
<w-datepicker label="Dato" name="date" lang="nb"></w-datepicker>
```

The component includes built-in locale support for `en`, `nb`, `sv`, `da`, and `fi`.

### Formatting

Use `header-format`, `weekday-format`, and `day-format` to control calendar display and accessible day labels.

```html
<w-datepicker
  label="Date"
  name="date"
  header-format="MMMM yyyy"
  weekday-format="EEEEEE"
  day-format="PPPP"
></w-datepicker>
```

These formats use `date-fns/format` syntax. Keep `day-format` descriptive because it is used as the accessible name for each day in the calendar.

### Disable Dates

Use `isDayDisabled` to prevent users from selecting certain dates from the calendar.

This property must be set on the element instance in JavaScript.

```html
<w-datepicker id="booking-date" label="Booking date" name="booking-date"></w-datepicker>

<script type="module">
  const datepicker = document.querySelector('#booking-date');

  datepicker.isDayDisabled = (day) => day.getDay() === 0;
</script>
```

Disabled dates cannot be selected from the calendar.

### About change events

With events the datepicker works much like the native `<input type="date">`:

- When the user types in the input field the component fires [`input` events](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
- When the user clicks a date in the calendar the component fires [`change` events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).

Note that the component does not fire a `change` event when typing in the input field. This is intentional.

You can listen to the [`blur` event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event) if you only care about getting a value, no matter if it was typed or chosen via the calendar. Note that the `blur` event might not fire if the user types and submits the form without leaving the input field. If you use the `blur` event to update JavaScript state you should read the value from the datepicker in your `submit` handler as well.

## Accessibility

Datepicker renders a labeled date input with a button that opens a calendar dialog. The calendar uses a grid of dates and moves focus into the calendar when it opens.

### Provide A Label

Always provide a visible label.

```html
<w-datepicker label="Departure date" name="departure"></w-datepicker>
```

The label should describe the date being requested. Avoid generic labels such as "Date" when there are several date fields on the same page.

### Calendar Dialog

The calendar popup is rendered as a dialog with `aria-modal="true"`. The month heading is announced with `aria-live="polite"` when users move between months.

Each date in the calendar grid has an accessible name formatted using `day-format`.

```html
<w-datepicker label="Date" name="date" day-format="PPPP"></w-datepicker>
```

Use a descriptive `day-format` so screen reader users hear the full date, not only the day number.
See [the Date FNS docs](https://date-fns.org/v4.1.0/docs/format) for formatting options.

## Examples

### Basic

<elements-example>

```html
<w-datepicker label="Date" name="date"></w-datepicker>
```

</elements-example>

### With Value

<elements-example>

```html
<w-datepicker label="Start date" name="start-date" value="2026-06-15"></w-datepicker>
```

</elements-example>

### Locale

<elements-example>

```html
<w-datepicker label="Dato" name="date" lang="nb"></w-datepicker>
```

</elements-example>

### Custom Formats

<elements-example>

```html
<w-datepicker
  label="Date"
  name="date"
  header-format="MMMM yyyy"
  weekday-format="EEEEEE"
  day-format="PPPP"
></w-datepicker>
```

</elements-example>

### Form Associated

<elements-example>

```html
<form>
  <w-datepicker label="Departure date" name="departure"></w-datepicker>
  <w-button type="submit">Search</w-button>
</form>
```

</elements-example>

### Disabled Calendar Dates

<elements-example>

```html
<w-datepicker id="booking-date" label="Booking date" name="booking-date"></w-datepicker>

<script type="module">
  const datepicker = document.querySelector('#booking-date');

  datepicker.isDayDisabled = (day) => day.getDay() === 0;
</script>
```

</elements-example>

## Styling API

## `<w-datepicker>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| calendar (JS only) | `HTMLDivElement` | `-` | - |
| day-format | `string` | `"PPPP"` | The date format used for calendar day accessible names. |
| header-format | `string` | `"MMMM yyyy"` | The date format used in the calendar header. |
| input (JS only) | `HTMLInputElement` | `-` | - |
| isCalendarOpen (JS only) | `boolean` | `false` | - |
| isDayDisabled (JS only) | `((day: Date) => boolean) \| undefined` | `-` | Function used to disable dates in the calendar. |
| label | `string \| undefined` | `-` | The label displayed above the date input. |
| lang | `string` | `-` | The locale used for calendar labels and date formatting. |
| month (JS only) | `unknown` | `-` | - |
| name | `string \| undefined` | `-` | The name submitted with the date value. |
| navigationDate (JS only) | `Date` | `-` | - |
| previousMonthButton (JS only) | `HTMLButtonElement` | `-` | This is the first focusable element, needed for the modal focus trap. |
| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
| selectedCell (JS only) | `HTMLTableCellElement` | `-` | - |
| selectedDate (JS only) | `Date \| null` | `-` | - |
| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
| todayCell (JS only) | `HTMLTableCellElement` | `-` | - |
| toggleButton (JS only) | `HTMLButtonElement` | `-` | - |
| value | `string \| undefined` | `-` | The selected date value. |
| weekday-format | `string` | `"EEEEEE"` | The weekday format shown above the calendar grid. |
| weeks (JS only) | `unknown` | `-` | - |
| wrapper (JS only) | `HTMLDivElement` | `-` | - |

### Property Details

#### calendar (JS only)



- Type: `HTMLDivElement`
- Default: `-`

#### day-format

The date format used for calendar day accessible names.

The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).

- Type: `string`
- Default: `"PPPP"`

#### header-format

The date format used in the calendar header.

The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).

- Type: `string`
- Default: `"MMMM yyyy"`

#### input (JS only)



- Type: `HTMLInputElement`
- Default: `-`

#### isCalendarOpen (JS only)



- Type: `boolean`
- Default: `false`

#### isDayDisabled (JS only)

Function used to disable dates in the calendar.

Set this on the element instance in JavaScript, not as an HTML attribute. Disabled dates cannot be selected from the calendar.

- Type: `((day: Date) => boolean) | undefined`
- Default: `-`

#### label

The label displayed above the date input.

Use this to give the datepicker a visible and accessible name.

- Type: `string | undefined`
- Default: `-`

#### lang

The locale used for calendar labels and date formatting.

This takes precedence over the `<html>` `lang` attribute. Supported built-in locales are `en`, `nb`, `sv`, `da`, and `fi`.

- Type: `string`
- Default: `-`

#### month (JS only)



- Type: `unknown`
- Default: `-`

#### name

The name submitted with the date value.

Use this when the datepicker belongs to a form and its value should be included in form data.

- Type: `string | undefined`
- Default: `-`

#### navigationDate (JS only)



- Type: `Date`
- Default: `-`

#### previousMonthButton (JS only)

This is the first focusable element, needed for the modal focus trap.

Don't cache this and other `@query` fields from inside the calendar modal.
They work the first time, but once the calendar is closed and reopened
the query will point to an element that doesn't exist anymore.

- Type: `HTMLButtonElement`
- Default: `-`

#### resetFormControl (JS only)



- Type: `resetFormControl() => void`
- Default: `-`

#### selectedCell (JS only)



- Type: `HTMLTableCellElement`
- Default: `-`

#### selectedDate (JS only)



- Type: `Date | null`
- Default: `-`

#### shadowRootOptions (JS only)



- Type: `object`
- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`

#### todayCell (JS only)



- Type: `HTMLTableCellElement`
- Default: `-`

#### toggleButton (JS only)



- Type: `HTMLButtonElement`
- Default: `-`

#### value

The selected date value.

Use an ISO date string in `YYYY-MM-DD` format. The value is submitted with the form and is reset to its initial value when the form resets.

- Type: `string | undefined`
- Default: `-`

#### weekday-format

The weekday format shown above the calendar grid.

The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).

- Type: `string`
- Default: `"EEEEEE"`

#### weeks (JS only)



- Type: `unknown`
- Default: `-`

#### wrapper (JS only)



- Type: `HTMLDivElement`
- Default: `-`

