| Table of Contents |
|---|
Description
Range pickers allow The range picker allows the user to set a customized range of dates using a unified component.
Much of the The range picker’s structure and behavior is are based on the Date Picker, and are therefore are not repeated here.
...
Usage & Behavior
General guidelines
Structure
Range pickers consist The range picker consists of:
A The range picker field, with two date inputs, for:
From date. The start of the range.
To date. The end of the range.
Date The date picker button. A calendar Icon Button which opens the calendar drop-down menu.Calendar
Preceding label (optional).
A drop-down range picker menu, which consists of:
Range picker menu, with month 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. |
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 calendar drop-downrange 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:
...
- Drop
Options should be disabled in the month and year drop-down selectors for months and years should be disabled 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 calendar drop-downrange picker menu.
Clicking either the From or To fields or the date picker icon will open the calendar drop-down 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.
   |
Interaction
Happy flow
 |  |  |
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.
...
Opens the The menu is opened:
...
|
...
|
...
|
...
|
...
|  |
2. Selecting the From date.
...
|
...
|
...
|  |
|
...
|
 |
3. Selecting the To date
|
...
|
...
|
...
the entire date range will be selected.
|
...
Additional cases
|
...
Clicking outside the menu (without selecting any date) is equivalent to the Cancel operation.
|
Directly editing an existing range.
|
...
|
...
If the From field is selected, the next selection in the menu will move focus to the To field.
 |  |
If the To field is selected, the next selection will close the menu.
 |  |
...
|  |
Selecting a date that is earlier than the currently selected From date, only the .
|
...
|  |
|
 |
Validations and errors
Validation is displayed on across the entire component.
Warning
Error |
|---|
 |
In the example, the From date is later than the To date (manually entered). | ||
Warning |  |
|---|
Transitions
The calendar drop-down Range picker menu should slide up and down (as with .
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).<TBD animations>
Best practices
Use:
Whenever whenever a user is required to set a custom period.
Don’t use:
When when a default set of ranges can be is pre-defined to satisfy the user → a Segmented Button 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. Example:
...
Accessibility compliance
Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility.
Design
Code
...