Component Date Range Picker

Anatomy

Date picker

1. Date picker: The calendar used to pick a date.
2. Date picker input: An input used to collect and display a date selection.
3. Month label: Shows the active month and year.
4. Day label: Labels the day of the week for a column in the calendar.
5. Navigation button: Toggles between months.
6. Selection indicator: Shows which date has been selected.
7. Date button: A clickable representation of dates in a month.
8. Popover: A common collapsible container for date picker components

Date range picker

The date range picker shares most of the same components as a date picker with the addition of the following:

9. Date range picker: A calendar used to select a date range.
10. Date range start: The first selected date in a date range.
11. Date range end: The last date selected in a date range.
12. Range selection indicator: Shows selected dates between a start and end date.

Calendar

Date picker calendars allow users to select a date contextually. For single date selections, one calendar is used. For selections of date ranges, two calendars may be visible in case a selection crosses into a second month.

Date picker input

The date picker input component is an input with an appended calendar icon. When focused, the date picker input opens a popover containing a date picker or a date range picker.

Input tooltips

Add a tooltip by setting the tooltip attribute to the desired text. Use tooltips sparingly, and keep text brief and supplementary. Do not include interactive elements. The tooltip appears on hover or keyboard focus.

<som-date-picker-input 
  id="dpiWithTooltip" 
  label="Date of birth" 
  horizontal-position="left" 
  vertical-position="bottom" 
  value="4/28/1984" 
  format="MM/DD/YYYY" 
  required-ind="none"
  tooltip="Format must be in MM/DD/YYYY."
></som-date-picker-input>

Containers

While not required, date pickers are usually placed inside containers such as popovers. This allows calendars to be separated from other content to avoid confusion or be collapsed and nested, so they are out of the way until needed.

How to use

Use a date picker:

• For scheduling purposes
• If it would be helpful for the date to be shown in context, such as in relation to the day of the week or proximity to the current date
• If the date being selected occurred recently or is in the near future

Use a date range picker if one or all the above conditions are met, but a user needs to select a range between two dates rather than a single date.

Date pickers use the standard American date format: MM/DD/YYYY. Since our audience is primarily people living within the U.S., this should not be changed.

Users should always be allowed to type in their desired date or date range manually, so be sure that the date picker is not the only way a user can input a date.

Don't rely exclusively on date pickers when collecting distant dates such as birthdays. It is frustrating for users to have to scroll to their birth year.

Behavior

Date pickers show the current month by default and, in the case of a multi-month date picker or a date range picker, will show the next month as well. Date pickers allow users to navigate between months and select dates, but it’s best to not use them for dates far into the future or long since past, such as birthdays. An input should be provided in these cases instead.

• Default: The standard state of a date button.
• Hover: When the cursor moves over a date without clicking it.
• Focus: When a user highlights a date button with a keyboard. The focus state looks different when selected vs. unselected.
• Disabled: A date that falls before a minimum date or after a maximum date.

Modifiers

Minimum and maximum dates can be used to limit possible user selections. Once set, only dates set after the min and before the max date will be selectable. All dates which fall outside of this range will be disabled.

For example, if a user is trying to schedule an appointment, a minimum date of “today” will prevent invalid appointments. Similarly, if an action has a deadline, a max date will prevent users from selecting a date beyond the deadline.

Date picker interactions

Mouse

• Clicking the calendar navigation arrows will change the visible month.
• Clicking a date button will select or deselect a date.
• Clicking a different date will change the selection.

Keyboard focus

• The tab key focuses into the date picker, beginning on the first month navigation button. Tabbing again will jump to the next month navigation button. Using an arrow key enters the calendar.
• Arrow keys navigate between dates in the calendar.
• Enter or space selects/deselects a date.
• Tab or Esc exits the calendar.

Date range picker interactions

Mouse

• Clicking into the input activates the cursor and allows typing.
• The date picker popover also opens for users.
• Clicking outside closes the date picker popover and removes focus from the input.

Keyboard focus

• Tabbing to the input focuses on the input and allows text entry.
• Pressing the down arrow key opens the date picker popover. The date picker can be navigated as described above.

Layout

Date picker and date range picker size

The height and width of a date picker and date range picker is set by default. If there is not enough room for both calendars in date range picker, only one is shown.

Date picker input size

The size of a date picker input is determined just like a standard input. On mobile devices, date pickers inside popovers grow to the full width of the screen.

Inline vs. nested

Date pickers can be placed inline or nested inside of popovers.

• When used inline, follow the standard rules for designing forms.
• Do not place separate date pickers next to one another horizontally, as this might confuse users.
• When nested inside a popover, place the control in accordance with rules for designing forms. The popover will open on top of other content where it has room.