Calendar Heatmap

data

An array of { date, value }. The example uses YYYY-MM-DD dates.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

• CalendarHeatmapData

  Type definition

width

Chart width in pixels. If the container width changes, update width from a ResizeObserver.

height

Chart height in pixels. Allow space for axes, titles, and the legend.

brandLogo

The default is the Syidax symbol and wordmark. With the Pro chart.branding entitlement, set none to remove it or provide a PNG, JPEG, or WebP data URL to replace it.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

brandPosition

The corner where the logo is anchored. Community and Pro both support all four corners, using the same position on screen and in image exports.

year

The range: a year (Jan 1 … Dec 31); start-date / end-date win over it; neither → the data's span.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

startDate

Set as an HTML attribute or JavaScript property. type: string.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

endDate

Set as an HTML attribute or JavaScript property. type: string.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

weekStart

monday or sunday.

• CalendarWeekStart

  Type definition

aggregate

How several entries on one day fold: sum (default), max, min, mean, last.

• CalendarAggregate

  Type definition

noDataValue

What a day without entries reads on the plane: a number (default 0 → the ramp's first colour) or nan (→ empty-color).

colors

The colour ramp (a scheme name, a colour list / comma list, or [t, colour] stops); default GitHub's greens.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

valueMin

Domain ends; an omitted end follows the data (the min includes the fill, so 0 is the ramp start).

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

valueMax

Set as an HTML attribute or JavaScript property. type: number.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

emptyColor

The colour of a NaN cell (the strip's corners outside the range, and no-data days under no-data-value="nan") — transparent by default.

cellGap

CSS px between cells.

cellRadius

The cell corner radius in CSS px.

cellBorder

Set as an HTML attribute or JavaScript property. type: number.

cellBorderColor

Set as an HTML attribute or JavaScript property. type: string.

renderPath

The draw path: auto (the cells path from 3 device px per cell — the usual case), or a forced plane / cells.

• CalendarHeatmapRenderPath

  Type definition

lod

Allowed values: auto, point, area, smooth. Default: 'auto'.

• HeatmapLodMode

  Type definition

monthLabels

Month labels along the top (a month whose label would overlap the previous one is skipped).

weekdayLabels

Weekday labels down the left: short (rows 0 / 2 / 4), all, none.

• CalendarWeekdayLabels

  Type definition

monthLines

Month boundaries as step lines between the cells.

chartTitle

The title inside the chart. Explain the data's unit and meaning alongside it.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

chartSubtitle

The subtitle inside the chart.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

enableMouseTracking

Set as an HTML attribute or JavaScript property. type: boolean.

tooltip

the cell tooltip (the shared cartesian tooltip input: show / trigger / format / html / connector / draggable …).

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

• CartesianTooltipInput

  Type definition

tooltipEnabled

Set as an HTML attribute or JavaScript property. type: boolean.

tooltipFormat

a plain-text formatter of the default tooltip (tooltip.format wins).

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

• CalendarHeatmapPointEventDetail

  Type definition

animated

Whether to animate initial display and data changes.

animationDuration

Animation duration in milliseconds.

animationEasing

Allowed values: linear, ease-out, ease-in, ease-in-out. Default: 'ease-out'.

• CalendarHeatmapEasing

  Type definition

animationType

Allowed values: initial, update. Default: undefined.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

• CalendarHeatmapAnimationType

  Type definition

streamSource

A stream source for live data. Check the contract for the specific type.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

• CalendarHeatmapStreamSource

  Type definition

streamMax

Streamed entries kept at most (default 10,000): the oldest leave first.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

streamWindow

The newest N streamed entries the chart folds in (the whole buffer when unset): the upserts of older entries revert to the data entries.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

visualMap

A visual-map binding; it overrides colors / value-min / value-max while bound.

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

• VisualMapBinding

  Type definition

zoom

Viewport zoom (Storybook parity, 2026-09-10) — the zoom attribute the cartesian charts carry: a mode ('x' | 'y' | 'xy'), true (x) or an object (mode / drag / keyboard / minRangePx / resetButton / pan / wheel / pinch / inside); off by default. The strip (the plot between the label bands) is the drawing rectangle — x runs 0 → 1 left to right over the weeks, y 0 → 1 bottom to top over the weekday rows — and the day cells are magnified into the window (their gap keeps its screen size); weeks and rows outside it leave the strip, the month lines, the labels and the hover / focus rings follow the visible cells. zoomTo / zoomBy / panBy / resetZoom work regardless of the gesture switches. Property-only (a mode string also works as an attribute).

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

• CartesianZoomInput

  Type definition

engine

Renderer selection: auto, standard, or pro. Engine selection is separate from permission to use a Pro chart type.

• CalendarHeatmapEngineMode

  Type definition

unavailable

Allowed values: fallback, error. Default: 'fallback'.

• CalendarHeatmapUnavailableBehaviour

  Type definition

rendered

Every drawn frame; engine is the engine status (requested / effective / code / the governing license feature).

Event name: rendered. Names are case-sensitive. Read the payload from detail on CustomEvent<CalendarHeatmapRenderResult & { tier: CalendarHeatmapEngineTier; engine?: ChartEngineStatus }>.

chart.addEventListener('rendered', event => {
  console.log(event.detail); // CalendarHeatmapRenderResult & { tier: CalendarHeatmapEngineTier; engine?: ChartEngineStatus }
});

• CalendarHeatmapRenderResult

  Type definition

• CalendarHeatmapEngineTier

  Type definition

• ChartEngineStatus

  Type definition

pointClick

A point selection event. Read the selected data and index from CustomEvent.detail.

Event name: pointClick. Names are case-sensitive. Read the payload from detail on CustomEvent<CalendarHeatmapPointEventDetail>.

chart.addEventListener('pointClick', event => {
  console.log(event.detail); // CalendarHeatmapPointEventDetail
});

• CalendarHeatmapPointEventDetail

  Type definition

pointHover

CustomEvent.detail type: CalendarHeatmapPointEventDetail | null. Event names are case-sensitive.

Event name: pointHover. Names are case-sensitive. Read the payload from detail on CustomEvent<CalendarHeatmapPointEventDetail | null>.

chart.addEventListener('pointHover', event => {
  console.log(event.detail); // CalendarHeatmapPointEventDetail | null
});

• CalendarHeatmapPointEventDetail

  Type definition

pointContextMenu

CustomEvent.detail type: ChartPointContextMenuEventDetail<CalendarHeatmapPointEventDetail>. Event names are case-sensitive.

Event name: pointContextMenu. Names are case-sensitive. Read the payload from detail on CustomEvent<ChartPointContextMenuEventDetail<CalendarHeatmapPointEventDetail>>.

chart.addEventListener('pointContextMenu', event => {
  console.log(event.detail); // ChartPointContextMenuEventDetail<CalendarHeatmapPointEventDetail>
});

• ChartPointContextMenuEventDetail

  Type definition

• CalendarHeatmapPointEventDetail

  Type definition

appended

CustomEvent.detail type: { count: number }. Event names are case-sensitive.

Event name: appended. Names are case-sensitive. Read the payload from detail on CustomEvent<{ count: number }>.

chart.addEventListener('appended', event => {
  console.log(event.detail); // { count: number }
});

windowSlid

CustomEvent.detail type: { dropped: number }. Event names are case-sensitive.

Event name: windowSlid. Names are case-sensitive. Read the payload from detail on CustomEvent<{ dropped: number }>.

chart.addEventListener('windowSlid', event => {
  console.log(event.detail); // { dropped: number }
});

chartAnimationStart

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: chartAnimationStart. Names are case-sensitive. Read the payload from detail on CustomEvent<void>.

chart.addEventListener('chartAnimationStart', event => {
  console.log(event.detail); // void
});

chartAnimationEnd

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: chartAnimationEnd. Names are case-sensitive. Read the payload from detail on CustomEvent<void>.

chart.addEventListener('chartAnimationEnd', event => {
  console.log(event.detail); // void
});

chartAnimationInterrupted

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: chartAnimationInterrupted. Names are case-sensitive. Read the payload from detail on CustomEvent<void>.

chart.addEventListener('chartAnimationInterrupted', event => {
  console.log(event.detail); // void
});

tooltipShow

Whether to display the built-in tooltip.

Event name: tooltipShow. Names are case-sensitive. Read the payload from detail on CustomEvent<CartesianTooltipEventDetail>.

chart.addEventListener('tooltipShow', event => {
  console.log(event.detail); // CartesianTooltipEventDetail
});

• CartesianTooltipEventDetail

  Type definition

tooltipHide

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: tooltipHide. Names are case-sensitive. Read the payload from detail on CustomEvent<void>.

chart.addEventListener('tooltipHide', event => {
  console.log(event.detail); // void
});

tooltipAction

CustomEvent.detail type: CartesianTooltipActionEventDetail. Event names are case-sensitive.

Event name: tooltipAction. Names are case-sensitive. Read the payload from detail on CustomEvent<CartesianTooltipActionEventDetail>.

chart.addEventListener('tooltipAction', event => {
  console.log(event.detail); // CartesianTooltipActionEventDetail
});

• CartesianTooltipActionEventDetail

  Type definition

zoomChange

Every zoom / pan change (drag, pan, wheel, pinch, keyboard, API, reset).

Event name: zoomChange. Names are case-sensitive. Read the payload from detail on CustomEvent<CartesianZoomChangeEventDetail>.

chart.addEventListener('zoomChange', event => {
  console.log(event.detail); // CartesianZoomChangeEventDetail
});

• CartesianZoomChangeEventDetail

  Type definition

getDataTable

Current normalized table, including the retained stream; independent of GPU availability.

getDataTable(): Promise<ChartDataTable>

Return type: Promise<ChartDataTable>. Call the method after element registration and await its Promise result.

• ChartDataTable

  Type definition

redraw

Redraw the chart using its current data and options. Inspect the rendered result after the returned Promise resolves.

redraw(): Promise<CalendarHeatmapRenderResult>

Return type: Promise<CalendarHeatmapRenderResult>. Call the method after element registration and await its Promise result.

• CalendarHeatmapRenderResult

  Type definition

getActiveTier

An asynchronous method. Check the argument and return types below.

getActiveTier(): Promise<CalendarHeatmapEngineTier>

Return type: Promise<CalendarHeatmapEngineTier>. Call the method after element registration and await its Promise result.

• CalendarHeatmapEngineTier

  Type definition

getUnavailableReason

Why the WebGPU renderer could not run (the fallback notice's reason); undefined when nothing fell back.

getUnavailableReason(): Promise<string | undefined>

Return type: Promise<string | undefined>. Call the method after element registration and await its Promise result.

setData

Replace the bar set.

setData(data: CalendarHeatmapData): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

• CalendarHeatmapData

  Type definition

appendPoint

Append one value to the stream. Check the argument type and the licensing requirements for streaming.

appendPoint(entry: CalendarHeatmapEntry): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

• CalendarHeatmapEntry

  Type definition

appendBatch

Append multiple values to the stream. Check the argument type and the licensing requirements for streaming.

appendBatch(entries: ReadonlyArray<CalendarHeatmapEntry>): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

• CalendarHeatmapEntry

  Type definition

shift

Drop the count oldest STREAMED entries (the data prop's entries are not a stream).

shift(count: number): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

replace

Swap the streamed set (replace([]) clears it); the base values never leave. Without chart.streaming the dies upsert into the base like a batch (quietly: no appended, no binChanged, as a ring replace).

replace(entries: ReadonlyArray<CalendarHeatmapEntry>): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

• CalendarHeatmapEntry

  Type definition

getStreamSource

The stream session's source (Chart Pro): like the stream methods it waits for a license still being confirmed.

getStreamSource(): Promise<CalendarHeatmapStreamSource | undefined>

Return type: Promise<CalendarHeatmapStreamSource | undefined>. Call the method after element registration and await its Promise result.

• CalendarHeatmapStreamSource

  Type definition

setAnimation

An asynchronous method. Check the argument and return types below.

setAnimation(options: { duration?: number; easing?: CalendarHeatmapEasing; enabled?: boolean; type?: CalendarHeatmapAnimationType }): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

• CalendarHeatmapEasing

  Type definition

• CalendarHeatmapAnimationType

  Type definition

pauseAnimation

Pause the current animation.

pauseAnimation(): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

resumeAnimation

Resume a paused animation.

resumeAnimation(): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

replayAnimation

Replay the initial sweep from min → value(s). No-op when animation is off / reduced.

replayAnimation(): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

hitTest

The day under host-relative CSS coordinates, or null (outside the strip, or a corner cell outside the range).

hitTest(cssX: number, cssY: number): Promise<CalendarHeatmapPointEventDetail | null>

Return type: Promise<CalendarHeatmapPointEventDetail | null>. Call the method after element registration and await its Promise result.

• CalendarHeatmapPointEventDetail

  Type definition

getCellValue

The folded value of a day (null for a day without entries or outside the range).

getCellValue(date: CalendarDateInput): Promise<number | null>

Return type: Promise<number | null>. Call the method after element registration and await its Promise result.

• CalendarDateInput

  Type definition

getValueExtent

The data's extent (the fill never counts).

getValueExtent(): Promise<CalendarHeatmapValueExtent | null>

Return type: Promise<CalendarHeatmapValueExtent | null>. Call the method after element registration and await its Promise result.

• CalendarHeatmapValueExtent

  Type definition

getGridSize

Columns × rows of the current grid.

getGridSize(): Promise<{ weeks: number; rows: number; cells: number; days: number; valued: number; entries: number; dropped: number }>

Return type: Promise<{ weeks: number; rows: number; cells: number; days: number; valued: number; entries: number; dropped: number }>. Call the method after element registration and await its Promise result.

getRange

The resolved range.

getRange(): Promise<CalendarHeatmapRange>

Return type: Promise<CalendarHeatmapRange>. Call the method after element registration and await its Promise result.

• CalendarHeatmapRange

  Type definition

getMonthMarks

The month marks (labels + boundary anchors).

getMonthMarks(): Promise<CalendarMonthMark[]>

Return type: Promise<CalendarMonthMark[]>. Call the method after element registration and await its Promise result.

• CalendarMonthMark

  Type definition

showTooltipAtCell

open the tooltip on a cell (week / weekday), honouring the tooltip input; null when the tooltip is off or the cell has no day.

showTooltipAtCell(week: number, weekday: number): Promise<CartesianTooltipEventDetail | null>

Return type: Promise<CartesianTooltipEventDetail | null>. Call the method after element registration and await its Promise result.

• CartesianTooltipEventDetail

  Type definition

showTooltipAtDate

open the tooltip on a day (null outside the range).

showTooltipAtDate(date: CalendarDateInput): Promise<CartesianTooltipEventDetail | null>

Return type: Promise<CartesianTooltipEventDetail | null>. Call the method after element registration and await its Promise result.

• CartesianTooltipEventDetail

  Type definition

• CalendarDateInput

  Type definition

showTooltipAtIndex

open the tooltip on a cell by its public index (week * 7 + weekday; the facade's showTooltipAtPoint).

showTooltipAtIndex(index: number): Promise<CartesianTooltipEventDetail | null>

Return type: Promise<CartesianTooltipEventDetail | null>. Call the method after element registration and await its Promise result.

• CartesianTooltipEventDetail

  Type definition

hideTooltip

Close the currently visible tooltip.

hideTooltip(): Promise<void>

Return type: Promise<void>. Call the method after element registration and await its Promise result.

focusCellAt

move the keyboard focus ring to a cell and announce it (null for a cell without a day).

focusCellAt(week: number, weekday: number): Promise<CalendarHeatmapPointEventDetail | null>

Return type: Promise<CalendarHeatmapPointEventDetail | null>. Call the method after element registration and await its Promise result.

• CalendarHeatmapPointEventDetail

  Type definition

focusDate

move the keyboard focus ring to a day (null outside the range).

focusDate(date: CalendarDateInput): Promise<CalendarHeatmapPointEventDetail | null>

Return type: Promise<CalendarHeatmapPointEventDetail | null>. Call the method after element registration and await its Promise result.

• CalendarHeatmapPointEventDetail

  Type definition

• CalendarDateInput

  Type definition

setVisualMap

Bind (or clear) a visual map: every mark is coloured through it on the next paint.

setVisualMap(binding: VisualMapBinding | null): Promise<VisualMapBinding | null>

Return type: Promise<VisualMapBinding | null>. Call the method after element registration and await its Promise result.

• VisualMapBinding

  Type definition

getVisualMap

An asynchronous method. Check the argument and return types below.

getVisualMap(): Promise<VisualMapBinding | null>

Return type: Promise<VisualMapBinding | null>. Call the method after element registration and await its Promise result.

• VisualMapBinding

  Type definition

getVisualExtent

The extent of a dimension: value = the day values, x = the week columns, y = the weekday rows, index = the cells.

getVisualExtent(request?: VisualMapExtentRequest): Promise<VisualMapExtent | null>

Return type: Promise<VisualMapExtent | null>. Call the method after element registration and await its Promise result.

• VisualMapExtent

  Type definition

• VisualMapExtentRequest

  Type definition

zoomTo

Zoom to explicit windows of the strip (x / y as { min, max } or [min, max] fractions 0 … 1; null clears that orientation).

zoomTo(request: CartesianZoomRequest): Promise<CartesianZoomChangeEventDetail | null>

Return type: Promise<CartesianZoomChangeEventDetail | null>. Call the method after element registration and await its Promise result.

• CartesianZoomChangeEventDetail

  Type definition

• CartesianZoomRequest

  Type definition

zoomBy

Scale the current windows by factor (< 1 zooms in) around anchorFraction (0..1, default centre).

zoomBy(factor: number, anchorFraction?: number): Promise<CartesianZoomChangeEventDetail | null>

Return type: Promise<CartesianZoomChangeEventDetail | null>. Call the method after element registration and await its Promise result.

• CartesianZoomChangeEventDetail

  Type definition

panBy

Slide the zoomed windows by fractions of the strip ({ x?, y? }); a no-op at the full extent.

panBy(delta: { x?: number; y?: number }): Promise<CartesianZoomChangeEventDetail | null>

Return type: Promise<CartesianZoomChangeEventDetail | null>. Call the method after element registration and await its Promise result.

• CartesianZoomChangeEventDetail

  Type definition

resetZoom

Reset the zoomed or panned range to the original data range.

resetZoom(): Promise<CartesianZoomChangeEventDetail | null>

Return type: Promise<CartesianZoomChangeEventDetail | null>. Call the method after element registration and await its Promise result.

• CartesianZoomChangeEventDetail

  Type definition

getZoom

Read the current zoom range. Check the return type's nullability and the range for each axis.

getZoom(): Promise<CartesianZoomState | null>

Return type: Promise<CartesianZoomState | null>. Call the method after element registration and await its Promise result.

• CartesianZoomState

  Type definition

getZoomExtent

The full extent of the viewport axes ([0, 1] each, key '0').

getZoomExtent(request?: CartesianZoomExtentRequest): Promise<CartesianZoomExtentDetail | null>

Return type: Promise<CartesianZoomExtentDetail | null>. Call the method after element registration and await its Promise result.

• CartesianZoomExtentDetail

  Type definition

• CartesianZoomExtentRequest

  Type definition

getEngineStatus

Requested engine vs what runs, and why (CHART-ADD-08): the decision for the current inputs, read without side effects (ProChartLicense.engineStatus); a renderer that failed at run time reports engine-unsupported.

getEngineStatus(): Promise<ChartEngineStatus>

Return type: Promise<ChartEngineStatus>. Call the method after element registration and await its Promise result.

• ChartEngineStatus

  Type definition