About Datepickers#

Implementation#

The datepicker is a form element, containing a label and text input, and a dropdown menu, containing a grid-based calendar and filters. The form element acts as a trigger for the dropdown.

Placement of inline form elements inside a data table cell is not supported. Instead, use a button to invoke a popover, which does support form elements.

The datepicker has the following markup requirements:

Desktop:

• Add .slds-is-open to the element with .slds-dropdown-trigger to invoke the dropdown that contains the datepicker.
• The .slds-is-selected modifier class is required on the td element that has the selected day.
• The .slds-is-today modifier class is required on the td element that is the current day.
• The .slds-has-multi-selection modifier class is required on the tr element that contains multiple days selected in the same week.
• The .slds-has-multi-row-selection modifier class is required on any tr element that contains multiple days selected in the multiple weeks.
• The .slds-is-selected-multi modifier class is required on the td element that contains a selected day within a range.

Mobile:

• When on mobile, we want to leverage the native date picker by changing the input type from text to date
• The input type="date" will create an input field allowing a date and time to be easily entered — this includes year, month, day.
• When switching input type="text" to input type="date" for mobile, we need to remove the ARIA attributes. The native rendering doesn't require these.
  • On the element with the class slds-combobox, please remove role="combobox", aria-expanded, and aria-haspopup.
  • On the input that we just added type="date" to, please remove aria-controls, aria-autocomplete, and role="textbox".

Accessibility#

Markup#

Dialog:

• Should act as a focus trap so the user only cycles through the datepicker dialog when the datepicker is open

Grid:

• Table must be labelled with role="grid" and be appropriately labelled with aria-labelledby
• Use aria-multiselectable="true" to allow for selection of multiple days
• Should act as a single focus stop

Gridcell:

• All dates should have role="gridcell" and aria-selected="false" on the gridcell by default
• If a date is selected, aria-selected should be set to true on the corresponding gridcell
• aria-current is used to indicate which day is today and should be set to aria-current="date"
• aria-label is used to provide the full DD MM YYYY text of the date

Opening the Datepicker:

• Mouse user: open the datepicker when a mouse user clicks on the input
• Keyboard user: only open the datepicker when a keyboard user presses enter or space on the datepicker button
  • Do not open the datepicker when user focus is on the input

Keyboard Interactions#

• When the datepicker opens, place user focus on either the currently selected date in the grid or if no date is selected the current day
• left and right arrow keys to navigate row
• up and down arrow keys to navigate between weeks on the same day
• home and end keys to jump to beginning or end of current row
• pagedown and pageup to navigate between months
• alt + pagedown and alt + pageup to navigate between years
• enter to select date and close datepicker
• esc to close datepicker without choosing a date

Base#

<div class="slds-form-element slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <label class="slds-form-element__label" for="date-input-id-default">Date</label>
  <div class="slds-form-element__control slds-input-has-icon slds-input-has-icon_right">
    <input type="text" id="date-input-id-default" placeholder=" " class="slds-input" />

States#

Date Selected#

<div class="slds-form-element slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <label class="slds-form-element__label" for="date-input-id-day_selected">Date</label>
  <div class="slds-form-element__control slds-input-has-icon slds-input-has-icon_right">
    <input type="text" id="date-input-id-day_selected" placeholder=" " class="slds-input" value="06/24/2021" />

Date Picker Has Error#

<div class="slds-form-element slds-has-error slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <label class="slds-form-element__label" for="date-input-id-error">Date</label>
  <div class="slds-form-element__control slds-input-has-icon slds-input-has-icon_right">
    <input type="text" id="date-input-id-error" placeholder=" " class="slds-input" />

Date Required#

<div class="slds-form-element slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <label class="slds-form-element__label" for="date-input-id-required">
    <abbr class="slds-required" title="required">* </abbr>Date</label>
  <div class="slds-form-element__control slds-input-has-icon slds-input-has-icon_right">

Date Required, Date Picker Has Error#

<div class="slds-form-element slds-has-error slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <label class="slds-form-element__label" for="date-input-id-required">
    <abbr class="slds-required" title="required">* </abbr>Date</label>
  <div class="slds-form-element__control slds-input-has-icon slds-input-has-icon_right">

Range#

<div class="slds-form slds-form_compound">
  <fieldset class="slds-form-element">
    <legend class="slds-form-element__label slds-form-element__legend">Start and End Date</legend>
    <div class="slds-form-element__control">

States#

Start Date Selected#

<div class="slds-form slds-form_compound">
  <fieldset class="slds-form-element">
    <legend class="slds-form-element__label slds-form-element__legend">Start and End Date</legend>
    <div class="slds-form-element__control">

End date selected (Same week)#

<div class="slds-form slds-form_compound">
  <fieldset class="slds-form-element">
    <legend class="slds-form-element__label slds-form-element__legend">Start and End Date</legend>
    <div class="slds-form-element__control">

End date selected (Different week)#

<div class="slds-form slds-form_compound">
  <fieldset class="slds-form-element">
    <legend class="slds-form-element__label slds-form-element__legend">Start and End Date</legend>
    <div class="slds-form-element__control">

Today - In selected range#

<div class="slds-form slds-form_compound">
  <fieldset class="slds-form-element">
    <legend class="slds-form-element__label slds-form-element__legend">Start and End Date</legend>
    <div class="slds-form-element__control">

Current And Adjacent Month In Selected Range#

<div class="slds-form slds-form_compound">
  <fieldset class="slds-form-element">
    <legend class="slds-form-element__label slds-form-element__legend">Start and End Date</legend>
    <div class="slds-form-element__control">