a-calendar
Calendar element for date or date-range selection.
The a-calendar element provides a fully accessible calendar for selecting single dates or date ranges. It supports localisation, highlighted dates, unavailable dates, and min/max constraints.
Installation
import "@sv/elements/calendar";Usage
Single date selection:
<a-calendar name="date" value="2024-03-15"></a-calendar>Date range selection:
<a-calendar mode="range" name="dates" value="2024-03-15/2024-03-20"></a-calendar>Custom locale and week start:
<a-calendar locale="de-DE" week-start="1"></a-calendar>Highlighted Dates
Highlight specific dates or ranges:
<a-calendar highlight="2024-03-15"></a-calendar>
<a-calendar highlight="2024-03-10/2024-03-16"></a-calendar>
<a-calendar highlight="2024-03-05,2024-03-15/2024-03-18,2024-03-25"></a-calendar>Unavailable Dates
Mark dates as unavailable:
<a-calendar unavailable="2024-03-15"></a-calendar>
<a-calendar unavailable="2024-03-10/2024-03-16"></a-calendar>Min/Max Constraints
Restrict selectable dates:
<a-calendar min="2024-03-01" max="2024-03-31"></a-calendar>CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--calendar-hover-bg | rgba(0,0,0,0.08) | Hover background color |
--calendar-selected-bg | #1d4ed8 | Selected date background |
--calendar-selected-color | white | Selected date text color |
--calendar-range-bg | rgba(29,78,216,0.2) | Range selection background |
--calendar-highlight-bg | rgba(234,179,8,0.4) | Highlighted date background |
--calendar-focus-outline | currentColor | Focus outline color |
Accessibility
- Keyboard Navigation: Full keyboard support for navigating dates with Arrow keys, Page Up/Down for months, and Enter to select.
- ARIA Labels: Days are labelled with full date information for screen readers.
- Focus Management: Focus is visible and moves logically through the calendar grid.
| Key | Action |
|---|---|
ArrowLeft / ArrowRight | Move to previous/next day |
ArrowUp / ArrowDown | Move to same day in previous/next week |
PageUp / PageDown | Move to previous/next month |
Home / End | Move to first/last day of month |
Enter / Space | Select the focused date |
CalendarElement
Calendar element for date or date-range selection. Supports different locales, week start configuration, and leap years.
Example
<a-calendar name="date" value="2024-03-15"></a-calendar>Attributes
| Name | Type | Default value | Description |
|---|---|---|---|
shadowRootOptions
|
ShadowRootInit | ... |
Options used when calling . Set this property to customize the options for the shadowRoot; for example, to create a closed shadowRoot: . Note, these options are used in . If this method is customized, options should be respected if possible. |
announcement
|
undefined | undefined |
Message announced to screen readers via the live region. Updated on navigation and selection so assistive tech gets feedback. |
disabled
|
undefined | undefined |
Whether the calendar is disabled. |
focusedDate
|
undefined | undefined |
Currently focused date for keyboard navigation. |
focusedYear
|
undefined | undefined |
Currently focused year for keyboard navigation in year picker. |
highlight
|
undefined | undefined |
Dates or ranges to highlight visually. Comma-separated list of dates (YYYY-MM-DD) or ranges (YYYY-MM-DD/YYYY-MM-DD). |
hoverDate
|
undefined | undefined |
Hovered date for range preview. |
locale
|
undefined | undefined |
BCP 47 locale tag for month/day names. |
max
|
undefined | undefined |
Maximum selectable date (YYYY-MM-DD). |
min
|
undefined | undefined |
Minimum selectable date (YYYY-MM-DD). |
mode
|
undefined | undefined |
Selection mode: "single" for single date, "range" for date range. |
name
|
undefined | undefined |
FormData name of the field. |
rangeFocus
|
undefined | undefined |
Which date of a range to focus for initial view month. Only applies when mode="range" and a value is provided. |
rangeStart
|
undefined | undefined |
Temporary range start during range selection. |
unavailable
|
undefined | undefined |
Dates or ranges to mark as unavailable. Comma-separated list of dates (YYYY-MM-DD) or ranges (YYYY-MM-DD/YYYY-MM-DD). |
value
|
undefined | undefined |
The value of the field. Single mode: "YYYY-MM-DD" Range mode: "YYYY-MM-DD/YYYY-MM-DD" |
viewDate
|
undefined | undefined |
Currently displayed month/year for navigation. |
weekStart
|
undefined | undefined |
First day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday). Defaults to locale-appropriate value. |
yearPickerOpen
|
undefined | undefined |
Whether the year picker menu is open. |
Events
| Name | Description |
|---|---|
change
|
Fired when the value changes (selection complete). |
input
|
Fired during range selection (intermediate states). |