Heatmap
Heatmap colors a row × column matrix by magnitude, for hour / day patterns, cohort comparisons or retention tables.
By default it uses a single-hue sequential scale (light = small, dark = large); diverging switches to two poles around midpoint, with neutral gray at the middle. Cells are 2px apart, and row / column labels are truncated to fit (the full text is in the tooltip and table). Empty cells get a neutral hatch pattern and are read as “No data”. The legend is a color gradient with min / max labels. Keyboard: Tab into the matrix, arrows move between cells, Home/End go to the start/end of the row.
Yugen Labs · experimentalThis component is outside SemVer: its API can change in a minor release, and What's new says so. Versioning policy
Visits by hour
Average of the last 4 weeks (thousands)
3110
Import
Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.
TSX
// npm install yugen-uiimport { Heatmap } from "yugen-ui";Variants
Each tile is a standalone example: hover to copy, or press Code to see the source.
Year-over-year growth
-30%0%+30%
Diverging
Signed data (up / down): diverging + a symmetric domain so both poles are equally dark; 0 is gray.
Retention by signup cohort
0%100%
Empty cells (cohort table)
null means “no data yet”. It is drawn with a neutral pattern, not the lightest color of the scale, which would read as “close to 0”.
Usage
Do
- Use a sequential scale for unsigned magnitudes; use a diverging scale only when the midpoint means something (0, a target, an average).
- Fix the domain when comparing several heatmaps, so the same color means the same value.
- Order rows / columns naturally (days of the week, hours) or by value so patterns show up.
Don't
- Don't use categorical colors for cells. A heatmap encodes magnitude, not identity.
- Don't give empty cells the lightest color. Missing data isn't the same as a small value.
- Don't cram number labels into small cells; the exact values are in the tooltip and table.
Props
| Prop · Type | Default | Description |
|---|---|---|
| data / indexChartDatum[] / string | Default: — | Each item is a row; index is the row label field. |
| columns{ key: string; label: string }[] | Default: — | Columns; null/missing = empty cell. |
| domain[number, number] | Default: from the data | Color domain; values outside it are clamped. |
| diverging / midpointboolean / number | Default: false / 0 | Diverging scale around midpoint. |
| valueFormatChartNumberFormat | Default: — | Value format (legend, tooltip, table). |
| rowHeightnumber | Default: 32 | Height of each row (px); the total height is computed. |
| legendboolean | Default: true | Color gradient with min / max labels (and the midpoint). |
| title, description, toolbar, locale, ariaLabel, indexLabel…ChartFrameProps | Default: — | Same as BarChart: frame, “Data table” button, texture, animate (off under reduced motion). |
Messages
Text built into the component: labels, aria-labels, screen reader announcements.
English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.
messages.chart
| Key · Type | Default (English) | messagesVi |
|---|---|---|
| roleDescriptionstring aria-roledescription của vùng vẽ. | Default (English)"chart" | messagesVi"biểu đồ" |
| heatmapRoleDescriptionstring | Default (English)"heat map" | messagesVi"bản đồ nhiệt" |
| dataTablestring Nút bật chế độ bảng của ChartContainer. | Default (English)"Data table" | messagesVi"Bảng dữ liệu" |
| totalstring Dòng tổng (tooltip, bảng) và nhãn giữa vòng DonutChart. | Default (English)"Total" | messagesVi"Tổng" |
| valuestring | Default (English)"Value" | messagesVi"Giá trị" |
| sharestring | Default (English)"Share" | messagesVi"Tỉ lệ" |
| noDatastring | Default (English)"No data" | messagesVi"Không có dữ liệu" |
| timestring Tiêu đề cột đầu của bảng (khi không truyền | Default (English)"Time" | messagesVi"Thời gian" |
| categorystring | Default (English)"Category" | messagesVi"Danh mục" |
| groupstring | Default (English)"Group" | messagesVi"Nhóm" |
| namestring | Default (English)"Name" | messagesVi"Tên" |
| otherstring Nhóm gộp (DonutChart vượt | Default (English)"Other" | messagesVi"Khác" |
| trendstring Nút bật đường xu hướng của ScatterChart. | Default (English)"Trend" | messagesVi"Xu hướng" |
| increasestring | Default (English)"Increase" | messagesVi"Tăng" |
| decreasestring | Default (English)"Decrease" | messagesVi"Giảm" |
| noChangestring | Default (English)"No change" | messagesVi"Không đổi" |
| brushstring ChartBrush: tên cửa sổ thu phóng, dòng "Đang xem … · n/N mốc", nút đặt lại. | Default (English)"Visible range" | messagesVi"Vùng xem" |
| brushRoleDescriptionstring | Default (English)"zoom window" | messagesVi"cửa sổ thu phóng" |
| brushViewingstring | Default (English)"Showing" | messagesVi"Đang xem" |
| brushPoints(shown: number, total: number) => string | Default (English)(shown, total) => `${shown}/${total} ${total === 1 ? "point" : "points"}` | messagesVi(shown, total) => `${shown}/${total} mốc` |
| brushResetstring | Default (English)"Reset" | messagesVi"Đặt lại" |
| lineSummary(info: { kind: "line" | "area" | "stacked" | "expand"; points: number; /** Mốc đầu / cuối (chỉ có khi points > 0). */ from?: string; to?: string; series: string[]; }) => string Mô tả truy cập tự sinh (khi không truyền | Default (English)Function, see messages.ts | messagesViFunction, see messages.ts |
| barSummary(info: { horizontal: boolean; stacked: boolean; categories: number; series: string[] }) => string | Default (English)Function, see messages.ts | messagesViFunction, see messages.ts |
| donutSummary(info: { groups: number; total: string; largest?: { label: string; share: string } }) => string | Default (English)Function, see messages.ts | messagesViFunction, see messages.ts |
| scatterSummary(info: { points: number; x: string; y: string; /** Tên đại lượng kích thước (biểu đồ bong bóng). */ size?: string; /** Tên các nhóm (khi có nhiều nhóm). */ groups?: string[]; trends: { group?: string; slope: string; r2: string }[]; }) => string | Default (English)Function, see messages.ts | messagesViFunction, see messages.ts |
| heatmapSummary(info: { rows: number; columns: number; min?: string; max?: string; hasEmpty: boolean }) => string | Default (English)Function, see messages.ts | messagesViFunction, see messages.ts |
| sparklineSummary(info: { points: number; first: string; last: string; min: string; max: string }) => string | Default (English)Function, see messages.ts | messagesVi({ points, first, last, min, max }) => `Xu hướng ${points} điểm: từ ${first} đến ${last}, thấp nhất ${min}, cao nhất ${max}` |