This component, combined with
<calendar-month>, is used to select a single date. It can display one or more months at a
time.
<calendar-date
value="2024-01-10"
min="2024-01-01"
max="2024-12-31"
locale="en-GB"
>
<calendar-month></calendar-month>
</calendar-date>
Properties and attributes
All dates are expected in ISO-8601 format (YYYY-MM-DD).
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
value | value | The currently selected date | 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 |
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> |
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 buttons |
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 |