DatePicker
DatePickers allow users to enter a date either through text input or by choosing a date from the calendar popover.
Design Usage
DatePickers are used to select a date or a date range as a standalone component, part of a fieldset, or as a filter.
Anatomy
DatePickers consist of an InputGroup with a button containing the calendar icon, and the calendar popover.
Input Group
The InputGroup triggers the calendar popover (see Behavior). It consists of a left-aligned button with the calendar icon and a field containing a formatted date (see Date Format). The InputGroup should always include a descriptive label.
Calendar Popover
The calendar popover allows users to select a date using the keyboard or a mouse.
Calendar Header
contains month name, days of the week, and arrows for navigating between months
Week
row containing days
Day
Selectable days within the shown month are black (#000000), days outside of the shown month are #72777B, and disabled days are #CCCCCC
Today Button [optional]
An optional button spanning the bottom of the calendar popover, enters the current date into the text field
Date Format
The date can be formatted as MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD. The format is based on the user’s account preferences.
Behavior
Interaction
Both the button and the input field composing the DatePicker’s InputGroup have focus/hover states when interacted with. Both will display the calendar popover upon selection. They return to their default states upon clicking outside the InputGroup or calendar popover.
Upon opening the calendar popover, the current month is displayed in the header and the current day is highlighted. Once a new date or date range is selected, either by typing into the input field or selecting a date in the popover, that same date will be selected in the calendar.
Selecting the optional Today button will display today’s date in the input field and close the calendar.
In the case of a DateRange (see Types below), whichever date is selected in one calendar, that same date will be shown as selected in the other.
Position
The calendar popover should never display even partially off screen. In general, it is left-aligned to the InputGroup.
Dismissing a Calendar Popover
The calendar popover disappears when a date is selected or by clicking outside of the popover or InputGroup.
Disabled State
DatePickers that can’t be selected because of unmet conditions are given the disabled state. Set the disabled property to change the state to disabled.
ReadOnly
A ReadOnly field cannot be modified. However, a user can tab to it, highlight it, and copy the text from it. Set the readOnly property to change the DatePicker’s state to ReadOnly.
For example, an Expense Report has been submitted and the Report Date still displays a field. The user may open the DatePicker but may not modify it.
Types
Default
A default DatePicker doesn’t utilize any customizations.
Date Range
When both Start Date and End Date are empty, any dates can be selected. Once a date is selected for Start Date, End Date will prevent the selection of a date prior to Start Date. Once a date is selected for End Date, Start Date will prevent the selection of a date after End Date.