FullCalendar Year Grid Plugin

Year views where each month is one row of day columns, subdivided into lanes — one row per group — with merged day chips, spanning bands, and per-lane metrics (a value per day, week or month).

Use

import { Calendar } from '@fullcalendar/core'
import yearGridPlugin from '@fullcalendar/yeargrid'

const calendar = new Calendar(el, {
  plugins: [yearGridPlugin],
  initialView: 'yearStripYear',
  initialDate: '2025-01-01',

  lanes: [
    { id: 'sa', title: 'SA', subtitle: 'Clara, Ryan, Grace', color: '#c6e0b4' },
    { id: 'other', title: 'Other', color: '#ffe699', events: 'band' },
    { id: 'avail', title: 'Available', events: 'none', metric: 'span', metricScale: 'week' },
  ],

  events: [
    { laneId: 'sa', start: '2025-01-02', end: '2025-01-04', title: 'C' },
    { laneId: 'other', start: '2025-03-10', end: '2026-03-10', title: 'Long leave' },
  ],

  metricSources: [
    { laneId: 'avail', values: [
      { week: '2025-01-05', value: 3, display: '3.0' },
      { week: '2025-01-12', value: 0, display: '0', classNames: ['fcy-metric-negative'] },
    ] },
  ],
})

calendar.render()

Views

| view | window | |---|---| | yearStripYear | twelve months | | yearStrip | no built-in duration — a calendar-level duration or visibleRange picks the window |

Both stack one month per row: a header of day numbers and weekday letters, then one row per lane.

Lanes

| field | meaning | |---|---| | id | referenced by events (laneId) and metric series | | title / subtitle | label reads title: subtitle | | color / textColor | lane label background, and the default colour of its events | | order, height, classNames | ordering and presentation | | events | merge (default), band, stack, none | | metric | badge, fill, text, span, none (default) | | metricScale | day (default), week, month |

Event modes. merge collapses every event overlapping a day into one chip (abbr falls back to title, joined by chipSeparator). band draws each event as a bar across its span, clipped at month edges, titled once at the start — all on one sub-row, so overlapping bars overlap. stack is band plus first-fit packing: overlapping spans get their own sub-row and the lane grows to fit. none means metrics only.

Metric modes. badge draws the value over the day cell's chip; fill colours the cell; text centres it; span merges the columns of a week or month into one cell.

Events

Plain FullCalendar events plus laneId (resourceId is accepted as an alias). Unknown top-level props land in extendedProps, so abbr is available there.

Metric series

metricSources: [{
  laneId: 'avail',
  scale: 'week',                    // defaults to the lane's metricScale
  values: [{
    week: '2025-01-05',             // or `date` for day scale, `month` for month scale
    value: 3.0,
    display: '3.0 FTE',             // defaults to String(value)
    color, textColor, classNames,
    tooltip: { /* opaque, handed to laneCellHover */ },
  }],
}]

Options

| option | default | meaning | |---|---|---| | lanes | one implicit lane | see above | | metricSources | [] | array, or a function of dateEnv | | stripAlign | 'weekday' | 'weekday' lines Mondays up across months; 'dayNumber' starts every month at column 1 | | chipSeparator | ', ' | joins merged chip parts | | yearLaneLabelWidth | 200 | px width of the label column | | yearMonthTitleFormat | { year:'numeric', month:'long' } | month heading | | unassignedEvents | 'drop' | 'default' puts events with no laneId into defaultLaneId |

Hooks

laneCellContent, laneCellClassNames, laneCellDidMount, laneCellWillUnmount, laneEventContent, laneMetricContent, laneHeaderContent, monthHeaderContent, laneCellClick, laneCellHover — FullCalendar's usual hook conventions, all with working defaults. Day cells also emit the standard dateClick carrying laneId, which needs @fullcalendar/interaction loaded.

Theming

Colours come from FullCalendar's own --fc-* variables, so standard themes and @fullcalendar/bootstrap5 apply unchanged. Ours, set on .fc:

| variable | default | |---|---| | --fcy-band-height | 1.35em — one sub-row in a stack lane | | --fcy-cell-min-height | 1.5em | | --fcy-font-size / --fcy-label-font-size | 0.75em / 0.85em | | --fcy-header-bg, --fcy-lane-label-bg, --fcy-weekend-bg | var(--fc-neutral-bg-color) | | --fcy-metric-negative-bg / --fcy-metric-negative-text | #ffc7ce / #9c0006 |

Not yet implemented

• yearBlocks — the month-as-a-square variant.
• Drag, resize and date-range selection: the view does not register hit-testing, so the interaction plugin's dragging does not apply to lane cells.

License

MIT, as upstream FullCalendar.