# Flux 2.0 — Heatmap A matrix of values on one sequential scale, where every cell can be focused and opened for its detail. Reference: https://flux.kaptio.com/components/heatmap/ Requires: https://flux.kaptio.com/tokens/v2/flux.css and flux-components.css ## Use it when Shows where values run high or low across two dimensions at once: occupancy by tour and month, a P&L line by period, a slice of usage by team and week. It is a real table, so the row and column headers name every cell, and each value is a button filled with one step of a five-step teal ramp and printed in the cell, so the colour is never the only way to read it. The grid is one tab stop: the arrow keys move between cells, and activating one opens its detail, typically in a Drawer. ## Do not use it when Not for a single series over time; use a Chart. Not for values that are categories rather than amounts, such as a status per day; use a Table with Badges. Not when people need to edit the values; use Editable cells in a Table. Not for more than about twelve columns at once; aggregate, or let the table scroll horizontally. ## Markup ### Occupancy by tour and month

	Apr	May	Jun	Jul	Aug	Sep
Golden Circle
South Coast
Snæfellsnes
Westfjords	No departures
Highlands	No departures	No departures

Under 50%
50–64%
65–79%
80–89%
90% and over

## API - flux-heatmap (class): On a figure, with data-flux-heatmap. It has no surface of its own; place it in a card or a section. - data-flux-heatmap (attribute): Binds the arrow keys, the roving tabindex and the detail fields. Requires flux-components.js. - flux-heatmap__header | __title | __summary (class): The figcaption, its heading and the pattern in words. - flux-heatmap__scroll | __table (class): The horizontal scroll container and the table, labelled with aria-labelledby. - flux-heatmap__cell (class): A button per value with data-step, an aria-label naming the row, the column and the value, and tabindex="0" on the first cell and "-1" on the rest. - data-step (attribute): 1 to 5, on a cell or a key swatch: the step of the sequential scale. - flux-heatmap__empty (class): A span in a cell with no value. - flux-heatmap__key | __swatch (class): The scale key and its swatches. - data-flux-heatmap-field (attribute): "row", "column" or "value", on elements in the dialog a cell opens. - flux-heatmap-select (element): Event dispatched from the heatmap when a cell is activated, with detail.row, detail.column, detail.value and detail.cell, for loading the record behind it. ## Accessibility - A native table with scoped headers, so screen readers can also move by row and column with their own table commands. - Each cell button names its row, column and value in its aria-label: "Golden Circle, Jul: 94%". - The value is printed in every cell; the colour is a second signal, never the only one. - The detail opens in a Drawer on the native dialog, so focus moves into it and returns to the cell when it closes. ## Keyboard - Tab: Moves into the grid, to the last cell used, and out again. - Arrow keys: Move one cell in that direction, skipping empty cells. - Home / End: Move to the first or last cell in the row. - Ctrl + Home / Ctrl + End: Move to the first or last cell in the grid. ⌘ on macOS. - Enter / Space: Opens the cell’s detail. ## Tokens - --flux-chart-sequential-1 to -5 and --flux-chart-sequential-text-1 to -5 (Tier 2) - --flux-heatmap-cell-height | -cell-min-width | -cell-gap | -cell-padding-x - --flux-heatmap-header | -row-header | -empty-text | -hover-ring | -key-swatch ## Do - State the pattern in the summary sentence, so nobody has to scan the grid to find it. - Choose step boundaries that mean something to the reader, and say them in the key. - Open the detail with the cell’s context in its title: the row, then the column. ## Do not - Do not use status or product colours as steps. The ramp is one teal, low to high. - Do not hide the values to make the grid look cleaner. - Do not put two measures in one heatmap. Make two.