The component consists of the following elements:

• trigger: shows the component label(s), current date value(s), and will render to reflect the state of the component (e.g. focus, hover, disabled, valid, invalid). The trigger includes one or two text inputs (depending on whether range is set) that allow the user to type a date directly.
• calendar: a monthly calendar grid rendered in a dropdown bib. Users can navigate between months and select dates by clicking or tapping calendar cells. On smaller viewports the calendar opens in a fullscreen modal dialog.
• help text: descriptive text rendered below the trigger intended to help clarify the intended use of the component instance and any current validation error with instructions to resolve those errors.

The trigger includes the component label(s) and the current date value(s). The label is required to ensure correct behavior with accessibility tools such as screen readers.

When range is set, two inputs are shown — one for the departure date and one for the return date — separated by a visual divider.

The trigger is a focusable element and will visually respond to common UI states — Hover (:hover), Focus (:focus / :focus-visible), Disabled (:disabled). The component does not have a visual response to the Active (:active) state.

The trigger contains the following elements that render conditionally:

• Calendar icon: a decorative calendar icon rendered to the left of the input field(s). Provides a visual cue that the component opens a calendar.
• Clear button: rendered when the input has a value, allowing the user to clear the current date selection.
• Validation error icon: rendered when the component is in an invalid state, visually indicating a validation problem.

The calendar displays one or more months in a grid layout. Users interact with the calendar by clicking, tapping, or using arrow keys to navigate date cells and Enter/Space to select. The calendar supports:

• Navigating between months using previous/next arrows.
• Arrow-key navigation between date cells with automatic cross-month boundary handling.
• Date range highlighting when range is set.
• Disabled dates outside the minDate/maxDate bounds.
• Blackout dates that are focusable but not selectable.
• Custom cell content via the date_YYYY_MM_DD slot.
• Cell popovers via the popover_YYYY_MM_DD slot.

Help text is not required. However, consideration should be given to how users will understand the full context of the component instance, particularly users reliant on accessibility tools like screen readers.

If the component fails validation, the help text will change to show a validation help message instead of the default help text.

When the component is used on a light background.

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

When the component is used on a darker background, set appearance="inverse" to invert the component colors for proper contrast and visibility.

<auro-datepicker appearance="inverse">
  <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>

The auro-datepicker component supports the shape, size and layout feature set. The component defaults to layout="classic", shape="classic" and size="lg".

The classic layout is default for auro-datepicker. No customization is needed to achieve this look.

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

The snowflake layout is a unique, one off layout that does not follow the normal pattern. There is only one way to use snowflake as shown in the following example.

The snowflake layout is only expected to be used on dark backgrounds, in conjunction with appearance="inverse".

<auro-datepicker layout="snowflake" shape="snowflake" appearance="inverse" placeholder="MM/DD/YYYY">
  <span slot="ariaLabel.bib.close">Close Calendar</span>
  <span slot="label">Date</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>