# Honeycomb (/docs/charts/honeycomb)

34 of 40 seats are taken: Honeycomb fills 34 cells of an area-filling hex grid. The unit is the cell, so the count is
countable, and this stays occupancy of a capacity rather than a magnitude. Cell size never changes with value, only the
count does. It fills row-major from the top left, so occupancy reads as a sweep, and the whole grid is exactly two SVG
paths (filled and empty) no matter how large the total.

```tsx
<Honeycomb value={34} total={40} unit="seats" title="Occupancy" cell={6} />
```

## Install

```tsx
import { Honeycomb } from "@microcharts/react/honeycomb";

<Honeycomb value={34} total={40} unit="seats" title="Occupancy" />
```

Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent.

## Try it

```tsx
import { Honeycomb } from "@microcharts/react/honeycomb/interactive";

<Honeycomb
  value={28}
  total={40}
/>
```

## When to use it

Use it for seats or licenses taken of a capacity, an occupancy read in a KPI card, or a countable of-total in a cell.
For a capacity over about sixty use `Progress`, and for a magnitude with no total, MiniBar. It isn't a trend chart, and
`PictogramRow` is the one that counts unlike things.

## Sizing

**strip mode for a table cell**

```tsx
<Honeycomb value={7} total={10} rows={1} />
```

**blank empties for a quieter, uncluttered surface**

```tsx
<Honeycomb value={28} total={40} empty="blank" />
```

## Variants

```tsx
<Honeycomb value={7} total={10} rows={1} />
<Honeycomb value={28} total={40} empty="blank" />
```

Empty cells are outlined by default, so takenness survives grayscale: a filled cell against an outlined one reads
without color. `empty="blank"` drops the empty cells entirely instead of dimming them, for surfaces where the outline
reads as noise. Packing is automatic, because a near-square comb is the recognizable form; `rows` overrides it.

## Edge cases

```tsx
<Honeycomb value={0} total={12} unit="seats" />
```

```tsx
<Honeycomb value={45} total={40} unit="seats" />
```

```tsx
<Honeycomb value={0} total={0} />
```

A value past the total fills every cell while the accessible name keeps the true number, so occupancy is never silently
clipped. Above sixty cells the counting stops working, so the chart emits a dev warning; reach for `Progress` there.

## Four homes

**In a sentence**

```tsx
<p>
  Seat occupancy{" "}
  <span className="mc-inline">
    <Honeycomb value={34} total={40} rows={2} summary={false} />
  </span>{" "}
  — 34 of 40 taken, one row left.
</p>
```

**In a table cell**

```tsx
<td>
  <Honeycomb value={34} total={40} rows={2} />
</td>
```

**In a KPI card**

```tsx
<div className="kpi">
  <span className="figure">34/40</span>
  <span className="unit">seats taken</span>
  <Honeycomb value={34} total={40} />
</div>
```

**In a tab header**

```tsx
<button className="tab">
  Room A <Honeycomb value={10} total={12} rows={2} />
</button>
```

## Accessibility

The accessible name is the exact occupancy — **"45 of 40 seats filled."** — always the true value, even when it exceeds
the total. The interactive entry announces the count on change through a polite live region and reveals the value and
total on hover. Focus it and the arrow keys rove cell by cell (←/→ within a row, ↑/↓ holding the column), each cell
announced as **"Cell 7 of 40 — filled."**

The interactive entry follows the shared [interaction contract](/docs/accessibility#one-interaction-contract):
arrow keys rove between units on both axes, `Home` and `End` jump to the ends, and a click, tap, `Enter` or
`Space` selects a unit — pinning its readout so it survives blur, until you select it again, press `Escape`, or
press outside the chart. On touch, a tap pins and a drag scrubs.

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `value` (required) | `number` | Filled count (fractional rounds). |
| `total` | `number` | Capacity = cell count (default 10). |
| `rows` | `number \| "auto"` | auto (near-square) or a number; 1 = strip. |
| `empty` | `"outline" \| "blank"` | How empty cells render (default outline). |
| `unit` | `string` | Noun for the summary (e.g. "seats"). |
| `label` | `"none" \| "count" \| "percent"` | Centered readout when the comb has room (default "none"). |
| `cell` | `number` | Hex cell radius in viewBox units (default 4). |
| `animate` | `boolean` | (interactive) Opt-in entrance motion when the chart mounts client-side — add `import "@microcharts/react/motion"` once. Inert on the server, on hydrated server HTML, and under `prefers-reduced-motion`. |

Plus the shared grammar — `data`, `domain`, `color`, `title`, `summary`, `format` — and the layout props (`width`, `height`, `className`, `style`) that every chart accepts. Interactive entries also share `animate` and `live`, and — wherever a chart has more than one navigable unit — `onActive`, `onSelect`, `selectedIndex` and `defaultSelectedIndex`; and — wherever the chart shows a hover value — `readout`. See [the shared grammar](/docs/quickstart#the-shared-grammar).