ChartHeatmap
Rectangular heatmap chart. Renders a grid of SVG <rect> cells coloured by value via CSS color-mix interpolation. Common uses: GitHub activity grids, correlation matrices, weekday × hour patterns.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-chart-heatmap> — 6 internal parts. Cell colour interpolated via CSS color-mix(in srgb, …).- 1.origam-chart-heatmap
- Root element. CSS grid with areas: header / body. role="figure" + aria-label from title.
- 2.origam-chart__heatmap-cell
- SVG
for each data cell. Fill is CSS color-mix interpolated between colorRange endpoints. tabindex="0" + role="button". - 3.origam-chart__heatmap-axis-label--y
- Y-axis row labels (left side). Hidden when showAxis=false.
- 4.origam-chart__heatmap-axis-label--x
- X-axis column labels (bottom). Hidden when showAxis=false.
- 5.origam-chart__heatmap-gradient-legend
- Inline SVG gradient bar with min/max value labels. Visible when showGradientLegend=true and legendPosition is top or bottom.
- 6.origam-chart-heatmap__header
- Title and subtitle block. Rendered only when title or subtitle is provided.
API
Props
All props accepted by this component, with their type, default value and description.
- xCategoriesArray<string>[]
- Explicit X-axis category ordering. When omitted, unique x values are sorted alphabetically/numerically.
- yCategoriesArray<string>[]
- Explicit Y-axis category ordering. When omitted, unique y values are sorted alphabetically/numerically.
- colorRange[TIntent | string, TIntent | string]['info', 'danger']
- Two-stop colour range. First entry = min value colour; second = max value colour. Accepts intent tokens or raw CSS strings.
- cellGapnumber2
- Gap between cells in SVG user units.
- showLabelbooleantrue
- Renders the numeric value centred inside each cell when the cell is large enough.
- showAxisbooleantrue
- Renders X and Y axis category labels along the grid edges.
- showGradientLegendbooleantrue
- Renders a gradient colour bar with min/max labels inline in the SVG.
- legendPositionTChartLegendPosition'bottom'
- Anchor of the gradient legend: 'top' | 'bottom' | 'left' | 'right'.
- xAxisFormat(value: string | number) => string
- X-axis column label formatter.
- yAxisFormat(value: number) => string
- Row label and gradient legend min/max formatter.
- seriesrequiredArray<IChartSeries>—
- Data series — only series[0] is consumed. Each datum must supply x, y and value.
- categoriesArray<string>
- titlestring
- Optional title rendered above the plotting area.
- subtitlestring
- Optional subtitle rendered below the title.
- showLegendbooleantrue
- Controls the ChartLegend visibility.
- showTooltipbooleantrue
- Shows a tooltip on hover/focus with x, y and formatted value.
- animatedbooleantrue
- Fades cells in on first paint. Respects prefers-reduced-motion.
- animationDurationnumber600
- Entry animation duration in ms.
- colorSchemeArray<TIntent | string>
- aspectRatiostring
- CSS aspect-ratio shortcut. When set, overrides height.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- heightnumber | string400
- Component height. Accepts a CSS length or a number (converted to px).
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- bgColor
- Background colour applied to the chart root.
- fontSizeTFontSize
- fontWeightTFontWeight
API
Slots
Content slots exposed by this component.
- #tooltip
- Replaces the default tooltip body for a hovered cell.
- #title
- Replaces the default title/subtitle block.
- #empty
- Shown when series is empty or has no renderable data.
API
Emits
Events emitted by this component.
- @point-clickIChartPoint, MouseEvent | KeyboardEvent
- Fired when the user clicks or keyboard-activates a cell.
- @legend-clickIChartSeries, number
- Fired when the user clicks a legend entry.
- @series-toggleIChartSeries, boolean
- Fired after a legend click with the intended next visibility value.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Gap between header and body areas.
- Internal padding of the chart root.
- Background colour of the chart root.
- Entry animation duration. Driven by animationDuration prop.
- Stroke colour of cell rects (creates visible gap between cells).
- Stroke width of cell rects.
- Font size of cell value labels.
- Fill colour of cell value labels.
- Font size of axis labels.
- Font size of the chart title.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Moves focus through each cell (tabindex="0"). |
| Enter / Space | Activates the focused cell, firing the point-click emit. |
Notes
- Root has role="figure" with aria-label from the title prop (falls back to "heatmap chart").
- The SVG carries role="img" with a <title> and <desc> listing column and row counts.
- Each cell has aria-label in the format "xCat × yCat: value" for screen reader announcement.
- Entry animations are disabled via @media (prefers-reduced-motion: reduce).
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic heatmap
Custom colour range
No cell labels
Ecosystem
Family
Components from the same folder that share conventions and often compose together.
Chart
Universal chart component supporting bar, line, area, pie, donut, scatter and more.
ChartBullet
Bullet chart — compact KPI display with range bands, actual-value bar and target tick.
ChartHoneycomb
Hexagonal tile-map chart for categorical or heatmap data.
ChartLegend
Standalone series-legend component shared by all chart families.
ChartMap
Choropleth and flight-route world map chart.