Lead: Asaf Ben-Oved
| Status | ||||
|---|---|---|---|---|
|
| Info |
|---|
Many of the Range Picker structure and behavior is based on Date Picker and <Time picker>, 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.
...
Sometimes used internally (Custom option) inside a Segmented button
...
...
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
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 top manual field displays the selected dates aligned with the calendric month
The direction of the dates might change according to RTL languages. |
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.The top manual field displays the selected dates aligned with the calendric month
If the range spend more than 2 months, the display of the calendric months will be set according to the selected field (From or To)
Interaction
The date fields can be manually typed 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
Selection flow is From (start) date -> To (end) date unless some exceptions (see below)
Opening the menu (Happy user flow)
Clicking either the From/To fields or the Date icon opens the menu
...
Clicking on the From Field or Icon
...
By default, the From Field is highlighted and text selected
Any selection on the menu will be considered as the From date
Clicking outside the menu is equivalent to the Cancel operation
Selecting a From date
...
Any selection on the menu will be considered as the From date
From field will be updated immediately
The focus will move to the To Field and reset it
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 only If .
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.
|  |
|
...
In case the user selects prior dates to the 1st date of the range the From field will update but focus will remain on the To field (the user didn’t complete selecting the To date yet)
...
Clicking outside the menu is equivalent to the Cancel operation
Selecting the To date (Happy user flow end)
...
Clicking on the To date will
Show range selection as selected
Update the To input field at the bottom
Removes all focus from the fields
Changes the Date icon to a “v” icon
Clicking on the V is equivalent to clicking outside the menu
...
|  |
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
...
If the user entered an invalid date/syntax in the manual field and tries to close the menu, use the behavior of connected cells in Field Validation
Displayed error upon Manually entering
...
displayed across the entire component.
Error |  | In the example, the From date is later than the To date |
|---|
...
To date which is earlier than the From date
Examples:
...
Error on the entire range picker
...
Error on a specific field in range picker
Transitions
...
A transition from Date icon to “v” icon
...
(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 needs is required to select 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
for example:
Future Version (TBD)
Adding a time picker within the menu so it will hold both dates and times at a unified component
Add a reset button to clear all fields
Accessibility compliance
...
Time Picker component adjacent to the range picker:
...
Accessibility compliance
Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility.
Design
Code
...