Skip to content

Calendar ​

An accessible, always-visible inline calendar. Supports day / month / year drill-down views, min/max bounds, disabled weekend days, theming, and native form association. Use this when you want the calendar rendered directly in the page: see Date Picker for the trigger + popup variant.

With Pre-selected Value ​

Full width

Min / Max Bounds ​

Full width

Disabled Weekends ​

Pass a JSON array of day-of-week indices (0 = Sunday … 6 = Saturday) to weekend-days.

Full width

Colors ​

Full width
Full width

Calendar Events ​

Pass an array of CalendarEvent objects via the events JS property. Each entry requires an id, a date (ISO 8601), and a label. An optional color accepts any CSS color value, and an optional endDate makes the event multi-day: it then renders on every day from date through endDate.

Normal mode: up to 3 colored dots per cell; additional events appear as a +N count.

Expanded mode: up to 3 colored pills with labels; additional events appear as +N more.

Full width

Expanded with events ​

Full width

Events overflow ​

When a day has more than 3 events, the first 3 are shown and the rest are summarised. This applies to both dots (normal mode) and pills (expanded mode).

Full width
Full width

Expanded Layout ​

Use expanded for a full-page, calendar-app style layout. Each day cell becomes tall with the day number shown as a circle in the top-left corner, leaving the remaining space for event content. The minimum cell height defaults to var(--size-28) and can be overridden with --calendar-expanded-cell-height.

Full width
Full width

Disabled ​

Full width

Localised ​

Full width

The locale also drives the grid order: fr-FR renders a Monday-first week, en-US a Sunday-first one, following the region's standard week info.

Week Start ​

Force a specific first day with week-starts-on (ISO numbering, 1 = Monday … 7 = Sunday). It overrides the locale-derived value, and unknown locales default to Monday.

html
<ore-calendar locale="en-US" week-starts-on="1" value="2025-06-15"></ore-calendar>

Chrome Labels ​

Navigation button names, the Today button, and the overflow pill live in the labels JavaScript property. Override only what you need:

js
const calendar = document.querySelector('ore-calendar');

calendar.labels = {
  previous: 'Zurück',
  next: 'Weiter',
  today: 'Heute',
  moreEvents: (count) => `+${count} weitere`,
};
KeyTypeDefaultWhere it appears
previousstring'Previous'Previous month/year button (a11y)
nextstring'Next'Next month/year button (a11y)
todaystring'Today'Footer shortcut button
moreEvents(count: number) => string+N moreExpanded-mode overflow pill

Today Shortcut ​

When the displayed month differs from the current month, a subtle Today button appears below the grid. It jumps the display back without changing the selection; it hides itself again once you're looking at the current month.

Full width

Inside a Form ​

Full width

Listening for Changes ​

js
document.querySelector('ore-calendar').addEventListener('change', (e) => {
  console.log(e.detail.isoValue); // '2025-06-15' or null
});

View Cycling ​

The header label button cycles through three views on each click:

  1. Day: the standard month grid; Previous/Next navigate by month
  2. Month: a 4×3 grid of abbreviated month names; click a month to return to day view at that month
  3. Year: a 4×3 grid of year numbers; click a year to go to month view for that year. Previous/Next page the window by whole decades

The calendar panel maintains a stable size across all three views: day view reserves space for a maximum 6-week month, and month/year views fill the same width.

API Reference ​

Props ​

PropTypeDefaultDescription
valuestringN/ASelected date in ISO 8601 format (yyyy-MM-dd)
minstringN/AEarliest selectable date (yyyy-MM-dd, inclusive)
maxstringN/ALatest selectable date (yyyy-MM-dd, inclusive)
weekend-daysnumber[][]JSON array of day-of-week indices to disable (0 = Sunday … 6 = Saturday). e.g. weekend-days="[0,6]"
week-starts-onnumberlocale week startFirst day of the week (ISO: 1 = Monday … 7 = Sunday). Overrides the locale-derived grid order
labelsPartial<CalendarLabels>defaultsChrome string overrides: previous, next, today, moreEvents (JS property)
localestringbrowser localeBCP 47 locale string for day/month names
colorstringN/ATheme color: primary | secondary | info | success | warning | error
sizestringmdComponent size: sm | md | lg
roundedstringN/ABorder radius override
disabledbooleanfalseDisable all interaction
requiredbooleanfalseRequired field (form association)
namestringN/AForm field name
eventsCalendarEvent[][]Calendar events to display. Dots in normal mode, pills in expanded mode. Set via JS property
expandedbooleanfalseExpanded calendar-app layout with tall cells and top-aligned day number circles
fullwidthbooleanfalseExpand calendar to full container width

CalendarEvent ​

FieldTypeRequiredDescription
idstringYesUnique identifier
datestringYesISO 8601 start date of the event (yyyy-MM-dd)
endDatestringN/AInclusive ISO end date (yyyy-MM-dd) for multi-day events
labelstringYesShort label shown in the cell (pill text in expanded mode)
colorstringN/AAny CSS color value. Falls back to the component's theme color

Events ​

EventDetailDescription
change{ isoValue: string | null }Fired when a date is selected. isoValue is the ISO 8601 date string or null when cleared

CSS Custom Properties ​

PropertyDefaultDescription
--calendar-bg--color-canvasCalendar background colour
--calendar-border-color--color-contrast-200Calendar border colour
--calendar-radius--radiusCalendar border radius
--calendar-shadow--shadow-mdCalendar drop shadow
--calendar-day-selected-bgtheme base colorBackground of the selected day cell
--calendar-day-today-colortheme base colorColor of today's date number
--calendar-day-outside-color--color-contrast-500Colour of day numbers outside the visible month
--calendar-expanded-cell-heightvar(--size-28)Minimum height of each day cell in the expanded layout

Parts ​

PartDescription
calendarThe root calendar panel
headerCalendar header (nav buttons + label)
gridThe day grid
dayIndividual day cell
footerFooter row holding the Today shortcut

Accessibility ​

ore-calendar implements the ARIA Grid Pattern. The host element carries role="group" and aria-label set to the currently visible month/year. Each view (day/month/year) uses role="grid" with cells grouped into role="row" elements: role="columnheader" for the day view's weekday headers, role="gridcell" on every day/month/year cell.

Selected days have aria-selected="true"; unselected days have aria-selected="false". Today's cell carries aria-current="date". Out-of-range and disabled-weekday cells have aria-disabled="true" and tabindex="-1", removing them from tab order. When the disabled attribute is set on the host, it receives aria-disabled="true", all cells become tabindex="-1", and no interaction is processed.

Keyboard Navigation ​

Day grid

KeyAction
ArrowRightMove focus to the next day
ArrowLeftMove focus to the previous day
ArrowDownMove focus one week forward (same weekday)
ArrowUpMove focus one week back (same weekday)
HomeMove focus to the first day of the current row
EndMove focus to the last day of the current row
Enter / SpaceSelect the focused day

Month and year grids

KeyAction
ArrowRightMove focus to the next cell
ArrowLeftMove focus to the previous cell
ArrowDownMove focus one row forward (4-column grid)
ArrowUpMove focus one row back (4-column grid)
HomeMove focus to the first cell of the current row
EndMove focus to the last cell of the current row
Enter / SpaceSelect the focused month / year

Header controls

KeyAction
Click / EnterPrevious / Next button: navigate by month or year
Click / EnterLabel button: cycle view: Day → Month → Year → Day
  • Date Picker: trigger + popup wrapper around the same calendar logic