# Usage heatmap
> Weekday-by-hour usage heatmap in which dot density is the value; the peak pulses, and hover or arrow keys show a cell's count.
- Element: `<hf-matrix>`
- React: `import { HfMatrix } from "@/components/lumesec/hf-matrix"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-matrix.json
- Page: https://elements.lumesec.ai/components/pixel-hd/matrix



Live preview: https://elements.lumesec.ai/view/hf-matrix

```html
<hf-matrix></hf-matrix>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-matrix
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-matrix.json
```

## Usage

React:

```tsx
import { HfMatrix } from "@/components/lumesec/hf-matrix";

export function Example() {
  return (
    <HfMatrix />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-matrix.js"></script>

<hf-matrix></hf-matrix>
```

## Behaviour

Weekday by hour. Each cell is a block of dots whose density is the value; the peak pulses, hovering adds a crosshair and the metrics morph into each other.

## API reference

### Attributes

| Attribute | React prop | Type     | Default                      | Description                         |
| --------- | ---------- | -------- | ---------------------------- | ----------------------------------- |
| `label`   | `label`    | `string` | `When your team uses Claude` | Heading text. Read once on connect. |

## Keyboard

| Keys                                         | Action                                                                                       |
| -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| ArrowLeft / ArrowRight / ArrowUp / ArrowDown | Move the inspected cell by one hour or one day. The first press starts from Wednesday 11:00. |

## Accessibility

* The heatmap canvas is focusable with `role="img"` and `aria-label` `Usage heatmap by weekday and hour. Use arrow keys to inspect cells.`
* The cell tooltip is plain text, not a live region, so inspected values are not announced.
* The Messages and Tokens switch is a `role="group"` labelled `Metric`, with `aria-pressed` buttons.
* Moving the pointer off the canvas or moving focus away hides the tooltip.
* Reduced motion: cells appear without the diagonal intro, metric changes apply at once, the peak cell does not pulse and drawing stops between interactions.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--border`, `--card`, `--foreground`, `--lumesec`, `--muted` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-border`, `--ui-fg`, `--ui-muted`, `--ui-raised`, `--ui-surface` and `--ui-track`.

## Notes

* Data is synthetic and built in: 7 × 24 values for messages (up to 420 per cell) and tokens (up to 48,000 per cell).
* The heatmap is 154px tall and fills the width. Without reduced motion it redraws every frame while visible.