This component, combined with
<calendar-month>
, is used to select a date range. It shows one or more months at a time.
<calendar-range
value="2024-01-10/2024-01-20"
min="2024-01-01"
max="2024-12-31"
locale="en-GB"
>
<calendar-month></calendar-month>
</calendar-range>
Properties and attributes
The value
property is expected in ISO-8601 range format (YYYY-MM-DD/YYYY-MM-DD
). All other dates are expected in ISO-8601 format (YYYY-MM-DD
).
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
value | value | The currently selected range | string | "" |
min | min | The earliest date that can be selected | string | "" |
max | max | The latest date that can be selected | string | "" |
focusedDate | focused-date | The date that is considered "focused" by the calendar | string | undefined |
tentative | tentative | The date that is tentatively selected e.g. the start of a range selection | string | "" |
firstDayOfWeek | first-day-of-week |
The first day of the week, where Sunday is 0 , Monday is
1 , etc
| number | 1 |
showOutsideDays | show-outside-days | Whether to show days outside the month | boolean | false |
locale | locale | The locale for formatting dates. If not set, will use the browser's locale | string | undefined | undefined |
months | months | The number of months to display per page | number | 1 |
pageBy | page-by |
Whether next and previous should move by number of months or
by a single month at a time
| "months" | "single" | "months" |
isDateDisallowed | - |
A function that takes a date and returns true if the date should
not be selectable
| (date: Date) => boolean | () => false |
Events
Emits non-bubbling CustomEvents
in response to user interaction.
Name | Description | Type |
---|---|---|
change |
Emitted when the value changes via user interaction. Not emitted
when value is programmatically changed
| Event |
focusday | Emitted when the currently focused day changes. This can happen via keyboard commands, or clicking the next or previous buttons | CustomEvent<Date> |
rangestart | Emitted when the user starts selecting a range | CustomEvent<Date> |
rangeend | Emitted when the user finished selections a range | CustomEvent<Date> |
Methods
Name | Description |
---|---|
focus |
Focuses the <calendar-month> containing the currently
focused date
|
CSS Parts
CSS parts allow for fine-grained styling and theming. They target specific elements inside the component. An element may have multiple parts, and a part may be used on multiple elements. They can be used in isolation, or combined.
See the guide on theming for a walkthrough of how to style this component.
Name | Description |
---|---|
container | The container for the entire component |
header | The container for heading and button s |
button | Any button within the component |
previous | The previous page button |
next | The next page button |
disabled | A button that is disabled due to min/max |
heading | The heading that labels the calendar |
Slots
Name | Description |
---|---|
Default slot |
The default slot is where you place your
<calendar-month> components, along with any other markup.
Note <calendar-month> does not need to be a direct descendant
|
previous | The inner content of the previous page button. By default uses text "Previous". You will likely want to slot an icon here |
next | The inner content of the next page button. By default uses text "Next". You will likely want to slot an icon here |
heading | By default displays the visible heading for the component. You may want to replace this with a year select. A separate visually-hidden heading is always rendered for accessibility purposes |