Heatmap

Code

import { Heatmap } from "@fadymondy/nasaq/web";const data = [  { date: "2026-09-27", count: 3 },  { date: "2026-09-28", count: 8 },  { date: "2026-09-29", count: 1 },];export function Activity() {  return <Heatmap data={data} to="2026-09-29" label="Commits by day" />;}

Charts & Maps · beta

Live examples and controls: Heatmap in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/heatmap.json

Shows how much happened on each day of a range: commits, orders, logins. Days are cells, weeks are columns and the cell's shade is its count relative to the busiest day. Labels for months and weekdays come from Intl, and the week starts on the locale's first day. Each cell opens a tooltip with the localized date and the count.

When to useCopy Anchor Link

• A year (or a few months) of activity where the pattern matters more than exact values.
• A compact "streak" view on a profile or dashboard.

When not to useCopy Anchor Link

• Exact values or trends: use a Chart.
• Picking a date: use a Calendar or DatePicker.

ImportCopy Anchor Link

import { Heatmap } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { Heatmap } from "@fadymondy/nasaq/web";

const data = [
  { date: "2026-09-27", count: 3 },
  { date: "2026-09-28", count: 8 },
  { date: "2026-09-29", count: 1 },
];

export function Activity() {
  return <Heatmap data={data} to="2026-09-29" label="Commits by day" />;
}

AnatomyCopy Anchor Link

Heatmap                       data-slot="heatmap"; sets dir and lang
├─ weekday labels             aria-hidden, every second row
├─ grid                       role="grid" (one tab stop)
│  └─ week column
│     ├─ month label          aria-hidden, on the week containing the 1st
│     └─ row                  role="row"
│        └─ cell              role="gridcell" data-date data-level, a Tooltip trigger
└─ legend                     Less, five levels, More     data-slot="heatmap-legend"

APICopy Anchor Link

HeatmapCopy Anchor Link

HeatmapDatumCopy Anchor Link

{ date: Date | string; count: number }. A string is a local day, "2026-09-29"; it is never read as UTC, so the day does not shift.

HelpersCopy Anchor Link

ExamplesCopy Anchor Link

Custom range, colour and unitCopy Anchor Link

import { Heatmap } from "@fadymondy/nasaq/web";

export function Orders({ data }: { data: { date: string; count: number }[] }) {
  return (
    <Heatmap
      data={data}
      from="2026-07-01"
      to="2026-09-29"
      color="var(--nq-tag-teal)"
      cellSize={16}
      gap={4}
      thresholds={[1, 4, 8, 12]}
      label="Orders by day"
      formatCount={(n) => `${n} orders`}
    />
  );
}

ArabicCopy Anchor Link

import { Heatmap, NasaqProvider } from "@fadymondy/nasaq/web";

export function ActivityAr({ data }: { data: { date: string; count: number }[] }) {
  return (
    <NasaqProvider locale="ar" target="scope">
      <Heatmap data={data} to="2026-09-29" label="الالتزامات حسب اليوم" />
    </NasaqProvider>
  );
}

AccessibilityCopy Anchor Link

The grid is role="grid" with weeks as rows and days as gridcells. Every cell has an accessible name such as "Sep 29, 2026: 3 contributions", so the value never depends on colour alone. There is one tab stop: the focused day (the last day at first). Cells are tooltip triggers, so the tooltip shows on focus as well as hover.

• Month names, weekday names and the legend are aria-hidden; the cells carry the full date.
• Caller must localise label and formatCount. Defaults exist for English and Arabic.

RTL & i18nCopy Anchor Link

• The week columns are a plain flex row under dir, so the oldest week is at the start edge: at the left in English and at the right in Arabic. Weekday labels sit at the start edge too.
• The week start comes from Intl.Locale (Saturday for ar, Sunday for en-US); weekStartsOn overrides it.
• Dates go through DateTime and formatDate, so digits are Western by default like the rest of Nasaq.
• The count text uses Arabic plural forms (zero, one, two, few, many).

Styling & tokensCopy Anchor Link

• The colour is one token, set as --heat on the root. The five levels are color-mix(in oklab, var(--heat) N%, transparent) with N of 9, 35, 55, 78 and 100. No hex.
• Cells use data-level (0 to 4) and data-date. Focus uses nq-focus.
• Size with cellSize and gap; extend the root with className. Never override colours with raw hex.

Do / Don'tCopy Anchor Link

• Do pass a formatCount with the real unit ("orders", "logins").
• Do pick a colour with enough contrast against the surface in light and dark; tag tokens do.
• Don't show it for very short ranges; use a list or a chart.
• Don't read colour alone for values; the tooltip and cell names carry the number.

RelatedCopy Anchor Link

• Chart · Calendar · Tooltip · StatCard

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-charts-maps-heatmap--docs