CalendarYearTable

A calendar grid for a grid of the twelve months of one year (typically 3 x 4 or 4 x 3 month cells). It is a structural wrapper on a <table role="grid"> with data-view="year": the consumer supplies the head, body and rows using the existing CalendarTable* sub-elements, and owns every date, locale format and cell.

Status: beta — implemented and unit-tested in the Svelte canonical; not yet exercised in composed flows.

CalendarYearTable is one of five calendar views alongside CalendarTable (the general-purpose grid). The component adds only a view-specific base class (calendar-year-table) and the data-view hook, so one stylesheet rule can lay out all five and views can be swapped without changing cell markup. Grid shape for this view: twelve month cells (for example 3 x 4); each cell usually links to or summarises one month.

Implementation Notes

• Renders <table class="calendar-year-table {class}" role="grid" aria-label={label} data-view="year">
• Renders a <caption> when caption is provided
• Reuses CalendarTableHead, CalendarTableBody, CalendarTableFoot, CalendarTableRow, CalendarTableTH and CalendarTableTD — there are no CalendarYearTable* sub-elements
• No internal state; the consumer owns locale formatting (use Intl.DateTimeFormat) and cell content
• Spreads restProps onto the root <table>

Props

Usage

<CalendarYearTable label="2025">
  <CalendarTableHead>
    <CalendarTableRow><CalendarTableTH scope="col">…</CalendarTableTH></CalendarTableRow>
  </CalendarTableHead>
  <CalendarTableBody>
    <CalendarTableRow><CalendarTableTD>…</CalendarTableTD></CalendarTableRow>
  </CalendarTableBody>
</CalendarYearTable>

Keyboard Interactions

ARIA

• role="grid" identifies the table as an interactive grid
• aria-label (from label) names the period shown
• data-view="year" is for consumer CSS and JS, not assistive technology

When to Use

• Showing a grid of the twelve months of one year (typically 3 x 4 or 4 x 3 month cells)
• Scheduling, booking and planner views that switch between periods
• When several calendar views share one stylesheet and need a stable data-view hook

When Not to Use

• Use CalendarTable when the view is not specifically year-scoped
• Use CalendarRangePicker to choose a date range, or DateInput to enter a single date
• Use DataTable for tabular data that is not a calendar
• Use GanttTable for tasks laid out across a time axis

Headless

The component decides semantics only: the table element, the grid role, the name and the view hook. It decides nothing about layout, colour, today/selected styling, or which dates appear.

Styles

Target .calendar-year-table or [data-view="year"] for view-specific layout. No default styles are included.

Testing

• Renders a <table> with role="grid" and class calendar-year-table
• label sets aria-label; data-view is year
• caption renders a <caption> only when provided
• Children and rest props are passed through

Advice

• Format every date with Intl.DateTimeFormat in the consumer; pass the already-formatted period as label.
• Give every cell an accessible name that includes its full date, not just the day number.
• Provide an obvious way to reach neighbouring periods (previous / next buttons outside the grid).

Related components

• calendar-table — the general-purpose calendar grid and its sub-elements
• CalendarMonthTable to drill into a month
• calendar-range-picker / date-input — typing a single date

References

• WAI-ARIA APG: Grid pattern
• WAI-ARIA APG: Date picker dialog example

Lily™ and Lily Design System™ are trademarks.