Design
Web component
Is documented
Status
Healthy
Figma component
Principles
Use when
- there's a need to assign dates such as creation, edit, collection, payment, etc., that will indicate aspects of a record.
- filtering a group of records by dates.
Use don’t when
- If it's a date that the user knows and can fill in by typing.
Structure
- Previous and next month buttons
- Month and year control
- Days of a week
- Day
- Selected day
- Range selection
- End-range
Properties
Types
Single
The single calendar allows the user to select a single day from a date.
Range
The range is used for selecting a group of days between two different dates in order to filter records created within that date range
States
In-range range-selected states is for range type only.
|
Default |
The default state is when the calendar shows the current day and has not selected any other day. |
|---|---|
|
Hover |
The hovering while the cursor hovers over any day on a calendar. |
|
Focus |
When navigation through on a calendar (while on the tab key), pressing enter will select day(s). |
|
Selected |
Specific day or a range of days actively selected. |
|
In-range |
The in-range state is when the start date is selected, highlighting the range to pick the end date. |
|
Range-selected |
The in-selected state is when both the start date and end date are selected, highlighting the selected range. |
Behavior
Interaction
Access to the calendar mostly occurs through date pickers and buttons. The calendar is not used independently most of the time. When we want to use the date picker, there are also other state properties to consider when interacting with the date picker (or button).
Disabled
Date pickers can be disabled in certain cases, such as when there is no permission to edit a date associated with a record or for collection and payment dates. Additionally, in some cases, it may not be possible to navigate back or forward between months and years.
Do
When a date picker is disabled, do not allow the calendar menu to open. Also, provide a relevant helper text explaining the reason based on the context.
Do
In some cases, selecting future dates may not be allowed. In such situations, keep the dates in a disabled state after the current date is selected.
Error / warning
While selecting a date or date range, a wrong or critical selection can be made. In such cases, the date-picker-input should provide feedback inline.
An error state is triggered if a user enters or selects a date outside the allowed date range.
If the selected date is for a delayed payment or collection, meaning there is a situation that requires caution on the selected date, it may be necessary to display these situations with a warning.
Do
An error state is triggered if a user enters or selects a date outside the allowed date range.
Do
If the selected date is for a delayed payment or collection, meaning there is a situation that requires caution on the selected date, it may be necessary to display these situations with a warning.
Month / year selection
The month and year selection can be done by using the previous/next buttons to navigate to in order. Additionally, clicking on the month and year text buttons allows you to jump to a specific date.
Positioning
A calendar, similar to an overflow menu, opens aligned to the left of its connected input or button after pressed.
Placement
When the calendar appears either via the date picker input or a button, it should always be on top. The calendar can be closed by selecting a date (or range) or by clicking outside of the component.
Content
Date formatting
The date format should match the system's default, which is typically DD/MM/YYYY as commonly used.
The date picker input field should not be left empty; it should be filled with the current date.
Do
The current day is selected by default.
Don't
Avoid using undefined dates as placeholders.