Light Dark System
Get ready for more awesome! Web Awesome, the next iteration of Shoelace, is on Kickstarter. Read Our Story

Calendar

<sl-calendar> | SlCalendar
Since 2.0 experimental

A calendar prototype for Shoelace.

<sl-calendar></sl-calendar>

Examples

Month & Day Labels

Month and day labels can be customized using the month-labels and day-labels attributes. Note that month names are localized automatically based on the component’s lang attribute, falling back to the document language. 

<sl-calendar month-labels="short" day-labels="narrow"></sl-calendar>

Showing Adjacent Dates

By default, only dates in the target month are shown. You can fill the grid with adjacent dates using the show-adjacent-dates attribute. 

<sl-calendar show-adjacent-dates></sl-calendar>

Date Selection

One or more dates can be selected by setting the selectedDates property. An array of dates is accepted and the selection does not have to be continuous. 

<sl-calendar class="calendar-selection"></sl-calendar>

<script>
  const calendar = document.querySelector('.calendar-selection');
  const today = new Date();

  // Set the selected date range from the 12-15 of the current month
  calendar.selectedDates = [
    new Date(today.getFullYear(), today.getMonth(), 12),
    new Date(today.getFullYear(), today.getMonth(), 13),
    new Date(today.getFullYear(), today.getMonth(), 14),
    new Date(today.getFullYear(), today.getMonth(), 15)
  ];
</script>

With Borders

To add a border, set the --border-width custom property. You can further customize the border with --border-color and --border-radius. 

<sl-calendar style="--border-width: 1px;"></sl-calendar>

Localizing the Calendar

By default, the calendar will use the document’s locale. You can use the lang attribute to change this. 

<sl-calendar lang="es"></sl-calendar>

[component-metadata:sl-calendar]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

Slots

Name Description
footer Optional content to place in the calendar’s footer.

Learn more about using slots.

Properties

Name Description Reflects Type Default
month The month to render, 1–12/ number -
year The year to render. number -
dayLabels
day-labels 		Determines how day labels are shown, e.g. “M”, “Mon”, or “Monday”. 'narrow' | 'short' | 'long' 'short'
monthLabels
month-labels 		Determines how month labels are shown, e.g. “J”, “Jan”, or “January”. 'numeric' | '2-digit' | 'long' | 'short' | 'narrow' 'long'
showAdjacentDates
show-adjacent-dates 		When true, dates from the previous and next month will also be shown to fill out the grid. boolean false
selectedDates Draws the target dates as a selection in the calendar. Date[] []
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
sl-change onSlChange Emitted when the date changes. -

Learn more about events.

Methods

Name Description Arguments
goToToday() Moves the calendar to the current month and year. -
goToPreviousMonth() Moves the calendar to the previous month. -
goToNextMonth() Moves the calendar to the next month. -

Learn more about methods.

Custom Properties

Name Description Default
--border-color The calendar’s border color.
--border-width The calendar’s border width.
--border-radius The border radius of the calendar.

Learn more about customizing CSS custom properties.

Parts

Name Description
day Targets day cells.
day-label Targets the day labels (the name of the days in the grid).
day-weekend Targets days that fall on weekends.
day-weekday Targets weekdays.
day-current-month Targets days in the current month.
day-previous-month Targets days in the previous month.
day-next-month Targets days in the next month.
day-today Targets today.
day-selected Targets selected days.
day-selection-start Targets days that begin a selection.
day-selection-end Targets days that end a selection.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-example>