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 a full month view to pick a date — for example, when context like weekdays, weekends, holidays or already booked days helps the choice. It works well embedded inside other components (such as the Date Field popover) or standalone in a panel.

Browsing dates

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

When not to use

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

Quick, known date entry

When users already know the exact date and just need to type it (for example a birth date), prefer the Date Field which combines free typing with a popover calendar.

Relative timeframes

Avoid the Calendar when only approximate periods or relative notions of time are needed (e.g. "next week", "this month"). Use radio buttons, a segmented control, or a select instead.

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	Day grid	Grid of selectable days for the visible month.	no
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.
Indicator: Days listed in indicator-dates show a visual marker.
Disabled (whole calendar): Non-interactive, muted.
Read-only: Visible state, no interaction.

Behavior

Selecting a date

Click a day or focus it with the keyboard and press Enter / Space to select it. Selecting a date emits an sl-change event.

Navigating months and years

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.

Min and max

Days outside the configured min / max range are visually disabled and cannot be selected.

Disabled and indicator dates

disabled-dates marks specific dates as non-selectable while still showing them in the grid. indicator-dates adds a visual marker to specific dates without changing their interactivity, which is useful for highlighting dates with events, deadlines or notifications.

Today

When show-today is set, today's date is visually highlighted to help users orient themselves in the current month.

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