Calendar

The calendar component allows users to select a single date or a range of dates from a visual calendar interface. It provides a consistent way to enable date selection within applications, supporting both single-date and range selection patterns.

Healthy

Show details

The calendar component is designed for visual date selection. For scenarios requiring direct text input or when users need to enter dates far in the past or future (e.g., birth dates), use Date Picker component instead. For filtering based on a specific date range, use filter component.

Anatomy

Month & Year select: Select controls that allow users to choose the displayed month and year.

Navigation buttons: Buttons used to move to the previous or next month, allowing users to navigate through the calendar.

Legend: A row displaying the abbreviated names or initials of the days of the week, helping users quickly identify columns.

Days grid: The main area of the calendar showing the dates of the selected month arranged in a 7-column grid, where each cell represents a day.

Usage Guidelines

When to use this component

Visual date selection

When users need to select a date or a date range from a visual calendar (e.g, selecting a day to display on a Calendar)

When not to use this component

Selecting very distant dates. Do not use a calendar for dates far in the past or future (over 10 years) as it can be tedious. Use a Date Picker instead.

Entering dates via text inputs. When the user experience requires direct text entry for dates, as this allows users to quickly type or paste a date, which can be more efficient in certain scenarios

General Component Behaviors

Highlighting current week

The calendar can visually highlight the current week. This helps users quickly orient themselves within the calendar and can provide clear context about the period currently in focus, especially when the calendar is part of a larger schedule or timeline.

Width

By default, the calendar adapts its width to fit its content. Calendar can be specified to fill full width of it’s parent container.

Closing on Selection

When the calendar is triggered by another element, it should close after a date is selected in single-date mode.
In range selection mode, it should close after both the start and end dates have been chosen.

Responsive Behavior

Items sizing

The calendar component adapts its item sizes to fit mobile screens, ensuring usability and readability across devices. On smaller screens, day cells, headers, and navigation controls automatically resize to optimize touch targets and layout.

States

Default: Indicates a day that is selectable.

Selected: Indicates a day that is selected, either as a single date or as the start or end date in a range.

Today: Indicates the current day.

Highlight: Indicates all days included within a selected range.

Blocked: Indicates a day that cannot be selected.

Muted: Indicates a day that falls outside the current month but is still selectable.

Variants

Single date selection

Enables users to select a single date from the calendar. This is the default interaction mode.

Range selection

Allows users to select a start and end date, with all dates in between highlighted.

Styles

Single-month

Displays one month at a time. Use when only a single date selection is required or when ranges are unlikely to span multiple months.

Multi-month

Displays multiple months side by side. Use when selecting ranges that may cross month boundaries.

Content Guidelines

Use proper locale and abbreviations for the country.

Start calendar week with a proper day for a country (Monday or Sunday)

For further information, see the Content Styleguide.