Enables a user to select a single date or range of dates in order to filter data for a particular time period. When applicable, users may also select from pre-defined ranges.

Examples

Visual best practices

Month and year

Day headers

Day numerals

Trigger

The date picker’s trigger is a complex element whose appearance must be adaptable to the context in which it’s presented. The trigger is often of equal importance in the hierarchy as it’s surrounding elements. However, the elements surrounding a trigger may differ, therefore lies it’s need for visual flexibilty.

Button example

<Box
    display="flex"
    justifyContent= "center"
>
    <Button
        appearance="outline"
        mr={300}
    >
        <Icon name="calendar" mr={300}/>
        1/17/2019 - 2/15/2020
    </Button>
    <Button
        appearance="outline"
        minWidth="36px"
        mr={300}
    >
        <Icon name="dotdotdot" />
    </Button>
    <Button
        appearance="outline"
        minWidth="36px"
    >
        <Icon name="export" mr={300} />
        Export
    </Button>
</Box>

Select example

<Box
    display="flex"
    justifyContent= "center"
>
    <Button
        border="1px"
        borderStyle="solid"
        borderColor="neutral.300"
        appearance="default"
        mr={400}
    >
        <Icon name="calendar" mr={300} />
            <Text
                fontWeight={400}
            >
                1/17/2019 - 2/15/2020
            </Text>
        <Icon name="chevron-down" color="neutral.500" ml={450} />
    </Button>
    <Select id='fruit'>
        <option value='apple'>Apple</option>
        <option value='orange'>Orange</option>
        <option value='banana'>Banana</option>
    </Select>
</Box>

Interaction best practices

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: 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 end date and the start date will be removed
  • The user may also select the same start and end date for single-date selection
  • The selected start date should have a filled background color, the user’s selection range remains unfilled and outlined with a border until an end date is selected at which point each day in the range is filled to match the start date’s background color and the border visually disappears
  • If picker calendar 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
• Multiple Date Range Selection (Comparison Periods)
  • Comparison date pickers: popout remains open until dismissed by user
  • Preset Comparison Date Range (Previous Period / Previous Year): After selecting date range end date, the date picker will remain open until dismissed by the user
  • Custom Comparison Date Range: After selecting date range end date, the selection is moved to the comparison period calendar, after selecting 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 and focus is returned to the first calendar’s start date

Comparison Interactions

• Default options:
  • Custom
  • Previous Period
  • Previous Year
• Previous Period defaults to the same number of prior days
• Selecting a date range of calendar month or calendar year with “Previous Period” Comparison will default to prior calendar month, if the prior month / year and display warning calling out “Comparing X days to Y days”, examples:
  • March vs February
  • Year vs Previous Year (leap year)
  • February vs Previous February (leap year)
• To get the same number of prior days, have to utilize the custom comparison period option

Disabled states

Disabled states should follow form and button rules around disabled styles

Quick links and presets

• Both the date range and comparison date range experiences feature quick links for easy date range selection
• Selecting a quick link (e.g., Previous Month, Previous 28 days or Previous 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, see “Do’s and Don’ts” section for additional guidelines
  • Custom
  • Previous 7 days
  • Previous Week
  • Previous 28 days
  • Previous Month

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