Calendar

The Calendar component displays a month view that lets users browse and select a date. It supports min/max constraints, disabled dates, indicator dates, week numbers and locale-aware formatting, and can be used standalone or embedded in other components such as the Date Field.

Usage

Code

Accessibility

  <sl-calendar aria-label="Choose a date"></sl-calendar>

When to use

The following guidance describes when to use the calendar component.

Visual date selection

Use the Calendar when users benefit from seeing dates in a full month view. This is useful when context such as weekdays, weekends, holidays, deadlines, or already booked days helps users make a clear date choice.

Browsing dates

Use the Calendar when users need to browse and orient themselves in time, for example to check which weekday a date falls on or to navigate between months and years before selecting a date.

Use the Calendar anywhere users need to navigate through dates and make a selection. This is useful when users need to move between months or years, explore available dates, or choose a date within a broader date-based workflow.

When not to use

The Calendar may not be the best choice in the following scenarios:

Date selection

Calendar is a standalone date navigation component designed for browsing and navigating days, months, and years in date-related content, rather than for simple date entry or relative timeframe selection. Use the Date Field when users need to enter a specific date, and use radio buttons, a segmented control, or a select for relative periods.

Anatomy

Item	Name	Description	Optional
1	Header	Displays the current month and year and the navigation controls.	no
2	Navigation buttons	Move to the previous or next month (and optionally year).	no
3	Weekday row	Localized day-of-week labels.	no
4	Week numbers	ISO week numbers next to each row.	yes
5	Grid	Grid of selectable days, month or year visible.	yes
6	Today indicator	Visual marker for today's date.	yes
7	Indicator dates	Visual markers for highlighted dates (e.g. events).	yes

States

Idle: No date selected or with a selected date highlighted.
Hover: Visual hover effects on focusable days.
Focus: Display the focus ring on the focused day.
Selected: Highlighted styling on the selected date.
Disabled day: Days outside min / max or in disabled-dates are styled as non-selectable.
Disabled (whole calendar): Non-interactive, muted.
Read-only: Visible state, no interaction.

Figma Properties

These properties describe the Figma setup for the Calendar. Some properties represent real component behaviour, while others are only used to preview or compose the component in Figma.

sl-calendar

Main component used to compose the Calendar and preview its available views.

Item	Options	Description
View	`Days` `Months` `Years`	Switches the Calendar preview between day, month, and year selection views.
Footer	`boolean`	Figma-only composition property. The footer is not part of the current code component and should move to the Date Field or Range Field Picker composition.

cal-header

Nested header component used to preview which view-switching buttons are available in the Calendar header.

Item	Options	Description
Month Button	`boolean`	Shows or hides the month button in the Calendar header.
Year Button	`boolean`	Shows or hides the year button in the Calendar header.
Decade Button	`boolean`	Shows or hides the decade button in the Calendar header.

date-cal-days_grid

Nested day grid component used to preview the day view layout.

Item	Options	Description
Weeks Number	`boolean`	Shows or hides week numbers in the day grid.

cal-months_grid

Nested month grid component used to compose the month selection view.

Item	Options	Description
Month grid	`nested component`	Displays selectable months when the Calendar is shown in the month view. No exposed Figma property was provided in the current screenshots.

cal-years_grid

Nested year grid component used to compose the year selection view.

Item	Options	Description
Year grid	`nested component`	Displays selectable years when the Calendar is shown in the year view. No exposed Figma property was provided in the current screenshots.

Behavior

Selecting a date

Click a day or focus it with the keyboard and press Enter / Space to select it.

Navigating through dates

Use the navigation buttons in the header, or use Page Up / Page Down (and Shift + Page Up / Shift + Page Down) to move between months and years from the keyboard.

Day indicators

Calendar day buttons can display different visual indications to help users understand the status of a date. When show-today is set, today's date is visually highlighted to help users orient themselves in the current month. Dates included in indicator-dates display a visual marker without changing their interactivity, which is useful for highlighting events, deadlines, or notifications. Dates included in disabled-dates, or dates outside the configured min and max range, remain visible in the grid but are shown as unavailable and cannot be selected.

Date Field: Input field that combines free typing with a calendar popover.
Time Field: Companion component for selecting a time.

  <sl-calendar aria-label="Choose a date"></sl-calendar>

Localization

Month names, day names and the first day of the week follow the active locale (via Intl.DateTimeFormat).
You can override the first day of the week with the first-day-of-week attribute (0 for Sunday, 1 for Monday, etc.).

Min and max constraints

Use the min and max attributes to restrict the selectable date range. Dates outside the range are visually disabled and cannot be selected.

Disabled and indicator dates

Use disabled-dates to mark specific dates as non-selectable (for example, holidays or already booked days). Use indicator-dates to highlight specific dates with a visual indicator (for example, dates with events) without disabling them.

Week numbers

Set show-week-numbers to display ISO week numbers next to each row of days.

Calendar API

Calendar component that combines day, month and year selection views to pick a date. Used internally by the date field, but can also be used standalone.

Properties

Name	Attribute	Type	Default	Description
`disabledDates`	`disabled-dates`	`Date[] \| undefined`		The list of dates that should be set as disabled.
`firstDayOfWeek`	`first-day-of-week`	`number \| undefined`		The first day of the week; 0 for Sunday, 1 for Monday.
`indicatorDates`	`indicator-dates`	`Indicator[] \| undefined`		The list of dates that should display an indicator. Each item has a `date` and optional `color` and `label` values that are used to improve accessibility.
`locale`	`locale`	`string`		The component's locale.
`max`	`max`	`Date \| undefined`	`undefined`	The maximum date selectable in the calendar.
`min`	`min`	`Date \| undefined`	`undefined`	The minimum date selectable in the calendar.
`month`	`month`	`Date \| undefined`		The month that the calendar opens on.
`readonly`	`readonly`	`boolean \| undefined`		Will disable the ability to select a date when set.
`selected`	`selected`	`Date \| undefined`		The selected date.
`showToday`	`show-today`	`boolean \| undefined`		Highlights today's date when set.
`showWeekNumbers`	`show-week-numbers`	`boolean \| undefined`		Shows the week numbers.

Events

Name	Event type	Description
`sl-change`	`SlChangeEvent<Date>`	Emits when the value changes.

Month view API

Low-level component that renders a single month grid without navigation controls. Used internally by select-day and can be used to compose custom calendar layouts.

Properties

Name	Attribute	Type	Default	Description
`disabledDates`	`disabled-dates`	`Date[] \| undefined`		The list of dates that should be disabled.
`firstDayOfWeek`	`first-day-of-week`	`number`	`1`	The first day of the week; 0 for Sunday, 1 for Monday. NOTE: Remove this property once `Intl.Locale.prototype.getWeekInfo` is widely available. See https://caniuse.com/mdn-javascript_builtins_intl_locale_getweekinfo
`getDayLabel`	-			Returns the default aria-label for a given day.
`getDayParts`	-			Returns an array of part names for a given day.
`hideDaysOtherMonths`	`hide-days-other-months`	`boolean \| undefined`	`false`	Will only show the days of the current month, not the next or previous, when true.
`indicatorDates`	`indicator-dates`	`Indicator[] \| undefined`		The list of dates that should display an indicator. Each item is an Indicator with a `date`, an optional `color` and 'label' that is used to improve accessibility (added as a tooltip).
`locale`	`locale`	`string`		The component's locale.
`max`	`max`	`Date \| undefined`	`undefined`	The maximum date selectable in the month.
`min`	`min`	`Date \| undefined`	`undefined`	The minimum date selectable in the month.
`month`	`month`	`Date`	`new Date()`	The current month to display.
`readonly`	`readonly`	`boolean \| undefined`	`false`	If set, will not render buttons for each day.
`renderer`	-	`MonthViewRenderer \| undefined`		You can customize how a day is rendered by providing a custom renderer callback.
`selected`	`selected`	`Date \| undefined`	`undefined`	The selected date.
`showToday`	`show-today`	`boolean \| undefined`	`false`	Highlights today's date when set.
`showWeekNumbers`	`show-week-numbers`	`boolean \| undefined`	`false`	Will render a column with the week numbers when true.

Methods

Name	Parameters	Return
`renderHeader`		`TemplateResult`
`renderDay`	`day: Day`	`TemplateResult`
`focus`	`options?: FocusOptions`	`void`
`focus`	`date: Date`	`void`
`focus`	`dateOrOptions?: Date \| FocusOptions`	`void`

Events

Name	Event type	Description
`sl-change`	`SlChangeEvent<Date>`	Emits when the user uses the keyboard to navigate to the next/previous month.
`sl-select`	`SlSelectEvent<Date>`	Emits when the user selects a day.

CSS Parts

Name	Description
`day`	The day button.
`disabled`	The day button when shown as disabled.
`indicator`	The day button for a date with an indicator.
`next-month`	The day button for a day in the next month.
`previous-month`	The day button for a day in the previous month.
`selected`	The day button for the selected date.
`today`	The day button for today's date.
`week-day`	The week day header cell.
`week-number`	The week number cell.

Keyboard interactions

The calendar supports full keyboard navigation through the month view, with shortcuts for moving between months and years.

Command	Description
Tab	Moves focus into and out of the calendar grid and the month/year navigation controls.
Arrow Left/Right	Moves focus to the previous or next day.
Arrow Up/Down	Moves focus to the same day in the previous or next week.
Page Up/Down	Moves focus to the same day in the previous or next month.
Shift + Page Up/Down	Moves focus to the same day in the previous or next year.
Home/End	Moves focus to the first or last day of the current week.
Enter/Space	Selects the currently focused date.

WAI-ARIA

In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningful value, because it relies on the context or way a component is used.

Attributes that we recommend you add in certain scenarios are mentioned below.

Attribute	Value	Description
`aria-label`	string	Defines a string that labels the calendar. Useful when the calendar is used standalone, without a surrounding labelled control.
`aria-labelledby`	string	References the ID of the element that labels the calendar.

Interactive example