A date picker enables users to select a single date or range of dates in order to filter data for a particular time period.

Date selection

• Upon clicking a trigger, the calendar pop-out should display with the current date range highlighted
• Clicking on any date will select that date for the active text input
• Dates that are not available cannot be selected, e.g., you cannot schedule a post in the past or review metrics/data in the future

Single date selection

In general, after a date selection has been made, the date picker should disappear or the user’s focus should shift, see below for guidelines for specific experiences:

• Single selection date pickers displayed within a : Popout closes
• Single selection date pickers displayed inline: no visual change

Date range selection

• If the user selects a start date that is past the end date, it will become the new start date and the end date will be removed
• If the user selects a start date that is before or on the end date, it will also become the new start date and the end date will remain
• If the user selects an end date that is before the start date, it will become the new start date and the end date will be removed
• The user may also select the same start and end date for single-date selection
• If selections match a date or date range preset, calendar should update to preset value
• After selecting a start date via the calendar, move to the respective end date
• After selecting an end date via the calendar, the date picker will close or focus on the next task

Comparison periods

• remains open until dismissed by user.
• Comparison time periods match the current time period by default.
• and are used as the background and border colors for the comparison period.

Preset comparison date range

After selecting a date range end date, the date picker will remain open until dismissed by the user.

Custom comparison date range

By selecting "custom" the user now manually selects the time period. After selecting a date range end date, the selection shifts to the comparison period. After selecting a comparison date range end date, the date picker will remain open until closed manually to allow the user to validate input and make any changes before applying their selections. Focus is returned to the original time period.

Content indicators

Content indicators can be used to show that content exists on a calendar day.

Disabled states

Disabled states should follow form element and button rules around disabled styles.

Quick links and presets

Date range and comparison date range experiences feature quick links for easy date range selection.

Selecting a quick link (e.g., Last Month, Last 28 days or Last Week) will automatically update the associated text inputs and date range.

• Preset selections can be overridden by manual date selection
• Analytics has a specific order for presets:
  • Custom
  • Last 7 days
  • Last Week
  • Last 28 days
  • Last Month
• Order presets and quick links by the most recent date in the set e.g., "Custom, Last 7 Days, Last Week, Last 28 Days, Last Month"

Accessibility

• Always pass a setStatusText prop so that screen reader users will hear a localized announcement of which month(s) are visible on screen.
• When a date picker is rendered in a , verify that the Popout can be closed with the Escape key. If the Popout is controlled (i.e., you are passing an isOpen prop to Popout), you must pass a setIsOpen prop in order for the Popout to close itself on Escape.

Resources

• Our Date Picker uses Airbnb's react-dates library as the base component
• Interaction patterns were inspired in part by Adphorus' React-date-range library
• 🔒 Meeting minutes from Sprout Product Design's April 2019 DatePicker-a-palooza