Calendar

The calendar allows users to select a specific date or range of dates.

Status

Status

Healthy

Figma component

Includes a link to a Figma component that has been imported to Supernova

Principles

Use when

  1. there's a need to assign dates such as creation, edit, collection, payment, etc., that will indicate aspects of a record.
  2. filtering a group of records by dates.

Use don’t when

  1. If it's a date that the user knows and can fill in by typing.

Structure

calendar-structure
  1. Previous and next month buttons
  2. Month and year control
  3. Days of a week
  4. Day
  5. Selected day
  6. Range selection
  7. 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

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.

calendar-interaction-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.

calendar-interaction-do-2

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.

calendar-interaction-do-3

An error state is triggered if a user enters or selects a date outside the allowed date range.

calendar-interaction-do-4

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.

calendar-positioning

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.

calendar-placement

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.

calendar-content-do

The current day is selected by default.

calendar-content-dont

Avoid using undefined dates as placeholders.

Figma source