Lead: Asaf Ben-Oved
| Status | ||||
|---|---|---|---|---|
|
| Info |
|---|
Many of the Range Picker structure and behavior is based on Date Picker and therefore are not described in this page |
Description
Range Picker
| Table of Contents |
|---|
Description
The range picker allows the user to set a customized range of dates with or without hours in using a unified component.
...
The range picker’s structure and behavior are based on the Date Picker, and are therefore are not repeated here.
...
Usage &
...
Behavior
General guidelines
Structure
...
Component
...
Image
...
Range picker field (Dates only)
...
Range picker menu (Dates only)
...
Range picker field (Dates and Time)
...
Range picker menu (Dates and Time)
...
Added presets Range picker
...
phase 1 see examples in Sketch
The Range picker field is composed of a string indicating the range (start - end) and an icon. The range picker consists of:
The range picker field, with two date inputs:
From date. The start of the range.
To date. The end of the range.
The date picker button. A calendar Icon Button which opens the drop-down menu.
Preceding label (optional).
A drop-down range picker menu, which consists of:
Month and year pickers for each half of the calendar.
Two month calendars.
Component | Image | Comments |
|---|---|---|
Range picker field |  | A string indicating the range (From - To) and an icon button. Next to the field, a preceding label |
...
can be set describing the purpose of the control. |
Range picker menu |
...
 |
...
2 month calendars, displayed horizontally from left (start) to right (end). The direction of the dates might change according to RTL languages. |
...
Beneath each of the calendar months, a manual input field is displayed.
Content
Usually used with a label “Date range”.
The bottom manual field also displays the selected dates from the top calendar months
Internal Logic
The months are always coupled which means the user always sees 2 consecutive months.
For example, if the user chooses to see the Januar 2020 on the End month (right side), the left side will show December 2019.Manual input
When a user selects a month both the Range picker and manual fields updates automatically
When a user enters a manual date both the Calendaric month and range picker field
Interaction
The external field can only be clicked upon, no manual entry of dates
Selection is always From (start) date -> To (end) date
Opening the menu
Clicking anywhere in the external field will open the menu
...
By default, the From Field is highlighted
This field only allows manual input by keyboard
Clicking outside the menu is equivalent to the Cancel operation
Selecting a From date
...
Clicking anywhere on either of the displayed calendar months will select that date as From and update the From Input Field at the bottom and the External field (
should the External field be updated immediately )The focus will move to the To Field
All dates prior to the From date are disabled
Clicking outside the menu is equivalent to the Cancel operation
Hovering for the To Date
...
A “trail” of hovered dates will be presented as the user hovers to select the To date
Clicking outside the menu is equivalent to the Cancel operation
Selecting the To date
...
Clicking on the To date will
Show range selection as selected
Update the To input field at the bottom
Enable all previously disabled dates (prior to 17 in the example)
Move the Focus back to the From input field
Clicking outside the menu is equivalent to the Apply operation
Validations and errors
Validation indication is presented immediately after the user makes the selection on the calendaric month
If the user entered an invalid date in the manual field and tries to close the menu, use the behavior of connected cells in Field Validation
Displayed error upon
Selecting a From date which is later than the To date
Selecting a To date which is earlier than the From date
Example of range picker (date and time):
...
Transitions
<<TBD>>
Best practices
<<e.g. Slider should display a label its on>>
Accessibility compliance
<<In general each component should be A11y complied, please follow the 3 guidelines linked below. At the very least we should document that each component is in compliance with each of the 3>>
Focus management
<<How will the component work with keyboard only - without a mouse. Can be reference if written above
We already set a general guidelines described in Keyboard & Focus Management Guidelines >>
Screen reader support
<<Make sure the components support screen reader for content or behaviour where needed - see Screen Reader Guidelines >>
Contrast & size compliance
...
Internal Logic
The months displayed in the menu can be changed independently.
The user cannot select a To (end) date which is earlier than the selected From (start) date, or a From (start) date which is later than the selected To (end) date.
The range picker field will be updated in response to selections made in the range picker menu.
When 2 consecutive months are displayed together on the menu, the arrows are disabled accordingly, so that the From month cannot be moved forward and the To month cannot be moved backward:
Options should be disabled in the month and year drop-down selectors to prevent a From date which is later than the To date. For example, if the From date is set to 2021, then 2020 and earlier will be disabled in the To date drop-down.
The two date inputs in the range picker field can always be directly edited, with no need to use the range picker menu.
Clicking either the From or To fields or the date picker icon will open the range picker menu with the relevant date selected (either From or To).
Clicking the date picker icon is equivalent to clicking on the From date.
 |  |  |
States
Date input field
State | Visual |
|---|---|
Regular |  |
Hover |  |
Active |  |
Disabled |  |
Read-Only |  |
Error |  |
Warning |  |
Focused |  |
Focused, Hover |  |
Focused, Active |  |
Focused, Disabled |  |
Interaction
1. Clicking on the From field.
...
The menu is opened:
|  |
2. Selecting the From date.
|  |
|  |
3. Selecting the To date
| |
Directly editing an existing range.
|  |
Selecting a date that is earlier than the selected From date.
|  |
|  |
Validations and errors
Validation is displayed across the entire component.
Error |  | In the example, the From date is later than the To date (manually entered). |
|---|---|---|
Warning |  |
Transitions
The Range picker menu should slide up and down.
Selecting the right and left arrows should swipe the dates horizontally. See the Date Picker for an example.
A swipe transition is used when pressing the left and right arrows to navigate between the months, as shown in the Date Picker.
Best practices
Use:
whenever a user is required to set a custom period.
Don’t use:
when a default set of ranges is pre-defined → a Selector can be a better approach for offering different periods.
General
If start and end times are also required, use the Time Picker component adjacent to the range picker:
...
Accessibility compliance
Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility.
Design
Code
...