Description

The <auro-datepicker> element allows users to select a date, or a pair of dates identifying a range, either with text input or by making a section in a calendar. The <auro-datepicker> element is the combination of auro-dropdown, auro-input, and Auro's extension of wc-range-datepicker.

User Stories

Select a date

Move focus to the datepicker input

The label moves from the placeholder position to the active position above the input area. The input is ready to accept a typed date value.
Click the input or press Enter / Space to open the calendar
The calendar bib opens and displays the current month. The focused cell is determined in the following priority order:
1. The currently selected date (if one exists and is within the valid min/max range).
2. Today's date (if it is enabled — within the min/max range).
3. The first future enabled date.
4. The first past enabled date.
Select a date by clicking a calendar cell or by typing a date directly into the input

When a valid date is selected, the value property is updated. The calendar remains open so additional dates can be reviewed. Close the calendar by pressing Escape or activating the Done button. If the user types a date, it must match the configured format (default mm/dd/yyyy).
Move focus away from the datepicker

Validation is triggered on blur by default. If the value does not meet the configured constraints (e.g. required, minDate, maxDate), the component renders an error state with a help text message.

Close Calendar Datepicker Headline Choose a date Choose a date

See code

<auro-datepicker>
  <span slot="ariaLabel.bib.close">Close Calendar</span>
  <span slot="bib.fullscreen.headline">Datepicker Headline</span>
  <span slot="fromLabel">Choose a date</span>
  <span slot="bib.fullscreen.fromLabel">Choose a date</span>
</auro-datepicker>

Select a date range

When the range attribute is set, the datepicker renders two inputs — one for the start date and one for the end date.

Select a departure date — the start date is set and focus moves to the return input
Select a return date — the end date is set and the date range is highlighted in the calendar

Close Calendar Datepicker Range Headline Departure Return Departure Return

See code

<auro-datepicker range>
  <span slot="ariaLabel.bib.close">Close Calendar</span>
  <span slot="bib.fullscreen.headline">Datepicker Range Headline</span>
  <span slot="fromLabel">Departure</span>
  <span slot="toLabel">Return</span>
  <span slot="bib.fullscreen.fromLabel">Departure</span>
  <span slot="bib.fullscreen.toLabel">Return</span>
</auro-datepicker>

Preset a value

Use the value attribute to set an initial date. For range datepickers, use both value and valueEnd to preset the full range.

Values may also be set programmatically at any time by updating the value and valueEnd properties via JavaScript.

Preset Date Departure Departure

See code

<auro-datepicker value="2026-06-15">
  <span slot="bib.fullscreen.headline">Preset Date</span>
  <span slot="fromLabel">Departure</span>
  <span slot="bib.fullscreen.fromLabel">Departure</span>
</auro-datepicker>

Preset Range Departure Return Departure Return

See code

<auro-datepicker range value="2026-06-15" valueEnd="2026-06-22">
  <span slot="bib.fullscreen.headline">Preset Range</span>
  <span slot="fromLabel">Departure</span>
  <span slot="toLabel">Return</span>
  <span slot="bib.fullscreen.fromLabel">Departure</span>
  <span slot="bib.fullscreen.toLabel">Return</span>
</auro-datepicker>

Skip selection

The datepicker does not force the user to select a date. If no selection is made and the field is not required, the user can move past the datepicker without entering a value.

If the field is required, moving focus away without selecting a date triggers validation and renders the valueMissing error state.

Popover slot

Use the popover_YYYY_MM_DD slot to display additional information when the user hovers over a calendar cell. This is useful for showing pricing, availability, or other contextual details for specific dates.

Popover Slot Example Choose a date Choose a date Tickets for this day are sold out $560 34 seats available $245 18 seats available $312 Tickets for this day are sold out $489 52 seats available $198 7 seats available $375 41 seats available $220

See code

<auro-datepicker centralDate="2023-12-03" calendarStartDate="2023-12-01" calendarEndDate="2023-12-31" minDate="2023-12-02" maxDate="2023-12-09">
  <span slot="bib.fullscreen.headline">Popover Slot Example</span>
  <span slot="fromLabel">Choose a date</span>
  <span slot="bib.fullscreen.fromLabel">Choose a date</span>
  <span slot="popover_2023_12_03">Tickets for this day are sold out</span>
  <span slot="date_2023_12_03">$560</span>
  <span slot="popover_2023_12_04">34 seats available</span>
  <span slot="date_2023_12_04">$245</span>
  <span slot="popover_2023_12_05">18 seats available</span>
  <span slot="date_2023_12_05">$312</span>
  <span slot="popover_2023_12_06">Tickets for this day are sold out</span>
  <span slot="date_2023_12_06">$489</span>
  <span slot="popover_2023_12_07">52 seats available</span>
  <span slot="date_2023_12_07">$198</span>
  <span slot="popover_2023_12_08">7 seats available</span>
  <span slot="date_2023_12_08">$375</span>
  <span slot="popover_2023_12_09">41 seats available</span>
  <span slot="date_2023_12_09">$220</span>
</auro-datepicker>

Blackout dates with custom label

Use the blackoutLabel attribute to customize the screen reader announcement for blackout (disabled but in-range) dates. The default label is "unavailable". This is useful when you want to provide more context about why a date cannot be selected, such as "sold out".

When a user types a blackout date into the input, the datepicker validates the entry and displays a customError message. The default message is "Selected date is unavailable". Use the setCustomValidityCustomError attribute to provide a custom error message, for example setCustomValidityCustomError="That date is sold out".

Choose a start date Choose an end date Choose a date Choose an end date

See code

<auro-datepicker id="blackoutLabelExample" range blackoutLabel="sold out">
  <span slot="fromLabel">Choose a start date</span>
  <span slot="toLabel">Choose an end date</span>
  <span slot="bib.fullscreen.fromLabel">Choose a date</span>
  <span slot="bib.fullscreen.toLabel">Choose an end date</span>
</auro-datepicker>

Reference dates

Use the referenceDates attribute to highlight specific dates on the calendar. Reference dates are displayed with a distinct visual treatment to draw attention to dates of interest, such as the cheapest travel dates or dates with special availability.

NOTE: it is recommended to provide popover slot content for reference dates to give context for why the date is marked reference.

Close Calendar Datepicker Headline Choose a date Choose a date Explanation for why this is a reference date. Explanation for why this is a reference date. Explanation for why this is a reference date. Explanation for why this is a reference date.

See code

<auro-datepicker referenceDates='["2025-10-05", "2025-10-15", "2025-10-20", "2025-10-22"]' minDate="2025-10-12" range>
  <span slot="ariaLabel.bib.close">Close Calendar</span>
  <span slot="bib.fullscreen.headline">Datepicker Headline</span>
  <span slot="fromLabel">Choose a date</span>
  <span slot="bib.fullscreen.fromLabel">Choose a date</span>
  <span slot="popover_2025_10_05">Explanation for why this is a reference date.</span>
  <span slot="popover_2025_10_15">Explanation for why this is a reference date.</span>
  <span slot="popover_2025_10_20">Explanation for why this is a reference date.</span>
  <span slot="popover_2025_10_22">Explanation for why this is a reference date.</span>
</auro-datepicker>

Viewport size

The datepicker automatically adapts its presentation based on viewport size. On larger screens, the calendar opens in a floating popover anchored to the trigger. On smaller screens, the calendar opens in a fullscreen dialog.

The breakpoint at which the fullscreen behavior activates is controlled by the fullscreenBreakpoint attribute. The default value is sm. Supported values are xs, sm, md, lg, xl, and disabled.

Close Calendar Datepicker Headline Choose a date Choose a date

See code

<auro-datepicker fullscreenBreakpoint="lg">
  <span slot="ariaLabel.bib.close">Close Calendar</span>
  <span slot="bib.fullscreen.headline">Datepicker Headline</span>
  <span slot="fromLabel">Choose a date</span>
  <span slot="bib.fullscreen.fromLabel">Choose a date</span>
</auro-datepicker>