Date picker - Elements

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

AndroidreleasedElementsreleasediOSreleasedReact 19released

Example theme:

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 for formatting options.

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.
When the user clicks a date in the calendar the component fires change events.

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

Examples

Basic

html

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

With Value

html

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

Locale

html

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

Custom Formats

html

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

Form Associated

html

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

Disabled Calendar Dates

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>

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`	`-`	-
checkValidity (JS only)	`checkValidity() => boolean`	`-`	Checks whether the textarea passes constraint validation
day-format	`string`	`"PPPP"`	The date format used for calendar day accessible names.
disabled	`boolean`	`false`	Makes the element not focusable and hides it from form submits
header-format	`string`	`"MMMM yyyy"`	The date format used in the calendar header.
help-text	`string \| undefined`	`-`	Description shown below the input field
input (JS only)	`HTMLInputElement`	`-`	-
invalid	`boolean`	`false`	Mark the form field as invalid.
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`	`-`	-
optional	`boolean`	`false`	Indicate visually that the field is optional
previousMonthButton (JS only)	`HTMLButtonElement`	`-`	This is the first focusable element, needed for the modal focus trap.
readonly	`boolean`	`false`	Whether the input can be selected but not changed by the user
reportValidity (JS only)	`reportValidity() => boolean`	`-`	Checks validity and shows the browser's validation message if invalid
required	`boolean`	`false`	Whether user input is required on the input before form submission
resetFormControl (JS only)	`resetFormControl() => void`	`-`	-
selectedCell (JS only)	`HTMLTableCellElement`	`-`	-
selectedDate (JS only)	`Date \| null`	`-`	-
setCustomValidity (JS only)	`setCustomValidity(message: string) => void`	`-`	Sets a custom validation message. Pass an empty string to clear.
shadowRootOptions (JS only)	`object`	`{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`	-
todayCell (JS only)	`HTMLTableCellElement`	`-`	-
toggleButton (JS only)	`HTMLButtonElement`	`-`	-
tooltip	`string \| undefined`	`-`	Supplementary information that should show in a tooltip behind an information icon after the label.
validationMessage (JS only)	`string`	`-`	Returns the validation message if the textarea is invalid, otherwise an empty string
validity (JS only)	`ValidityState`	`-`	Returns the validity state of the textarea
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: -

checkValidity (JS only)

Checks whether the textarea passes constraint validation

Type: checkValidity() => boolean
Default: -

day-format

The date format used for calendar day accessible names.

The syntax is defined by date-fns/format.

Type: string
Default: "PPPP"

disabled

Keep in mind that using disabled in its current form is an anti-pattern.

There will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.

Please consider more informative alternatives before choosing to use disabled on an element.

Type: boolean
Default: false

header-format

The date format used in the calendar header.

The syntax is defined by date-fns/format.

Type: string
Default: "MMMM yyyy"

help-text

Use in combination with invalid to show as a validation error message, or on its own to show a help text.

Type: string | undefined
Default: -

input (JS only)

Type: HTMLInputElement
Default: -

invalid

Mark the form field as invalid.

Make sure to also set a help-text to help users fix the validation problem.

Type: boolean
Default: false

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: -

optional

Indicate visually that the field is optional

Type: boolean
Default: false

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: -

readonly

Whether the input can be selected but not changed by the user

Type: boolean
Default: false

reportValidity (JS only)

Checks validity and shows the browser's validation message if invalid

Type: reportValidity() => boolean
Default: -

required

Whether user input is required on the input before form submission

Type: boolean
Default: false

resetFormControl (JS only)

Type: resetFormControl() => void
Default: -

selectedCell (JS only)

Type: HTMLTableCellElement
Default: -

selectedDate (JS only)

Type: Date | null
Default: -

setCustomValidity (JS only)

Sets a custom validation message. Pass an empty string to clear.

Type: setCustomValidity(message: string) => void
Default: -

shadowRootOptions (JS only)

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

todayCell (JS only)

Type: HTMLTableCellElement
Default: -

toggleButton (JS only)

Type: HTMLButtonElement
Default: -

Supplementary information that should show in a tooltip behind an information icon after the label.

You must provide a label to be able to show an info icon with a tooltip.

Type: string | undefined
Default: -

validationMessage (JS only)

Returns the validation message if the textarea is invalid, otherwise an empty string

Type: string
Default: -

validity (JS only)

Returns the validity state of the textarea

Type: ValidityState
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.

Type: string
Default: "EEEEEE"

weeks (JS only)

Type: unknown
Default: -

wrapper (JS only)

Type: HTMLDivElement
Default: -

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system

Date picker - Elements ​

Accessibility ​

Provide A Label ​

Calendar Dialog ​

Usage ​

Basic Datepicker ​

Value ​

Locale ​

Formatting ​

Disable Dates ​

About change events ​

Examples ​

Basic ​

With Value ​

Locale ​

Custom Formats ​

Form Associated ​

Disabled Calendar Dates ​

Styling API ​

<w-datepicker> API ​

Properties ​

Property Details ​

calendar (JS only) ​

checkValidity (JS only) ​

day-format ​

disabled ​

header-format ​

help-text ​

input (JS only) ​

invalid ​

isCalendarOpen (JS only) ​

isDayDisabled (JS only) ​

label ​

lang ​

month (JS only) ​

name ​

navigationDate (JS only) ​

optional ​

previousMonthButton (JS only) ​

readonly ​

reportValidity (JS only) ​

required ​

resetFormControl (JS only) ​

selectedCell (JS only) ​

selectedDate (JS only) ​

setCustomValidity (JS only) ​

shadowRootOptions (JS only) ​

todayCell (JS only) ​

toggleButton (JS only) ​

tooltip ​

validationMessage (JS only) ​

validity (JS only) ​

value ​

weekday-format ​

weeks (JS only) ​

wrapper (JS only) ​

Questions? ​

Date picker - Elements

Accessibility

Provide A Label

Calendar Dialog

Usage

Basic Datepicker

Value

Locale

Formatting

Disable Dates

About change events

Examples

Basic

With Value

Locale

Custom Formats

Form Associated

Disabled Calendar Dates

Styling API

`<w-datepicker>` API

Properties

Property Details

calendar (JS only)

checkValidity (JS only)

day-format

disabled

header-format

help-text

input (JS only)

invalid

isCalendarOpen (JS only)

isDayDisabled (JS only)

label

lang

month (JS only)

name

navigationDate (JS only)

optional

previousMonthButton (JS only)

readonly

reportValidity (JS only)

required

resetFormControl (JS only)

selectedCell (JS only)

selectedDate (JS only)

setCustomValidity (JS only)

shadowRootOptions (JS only)

todayCell (JS only)

toggleButton (JS only)

tooltip

validationMessage (JS only)

validity (JS only)

value

weekday-format

weeks (JS only)

wrapper (JS only)

Questions?