# Honeycomb (/docs/charts/honeycomb)

Honeycomb answers "how many of the available slots are taken?" as filled cells in an area-filling hex grid. The unit is
the cell, so the count is genuinely countable — this is occupancy of a capacity, not a magnitude. 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.


## When to use it

- **Good for** — seats or licenses taken of a capacity, an occupancy read in a KPI card, or a countable of-total in a
  cell.
- **Avoid for** — a capacity over about sixty (that's `Progress`), a magnitude with no total (MiniBar), or trends.


## Variants

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

## Edge cases

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

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

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


## Why this default

Outline empties are the default because takenness must survive grayscale — a filled cell versus an outlined cell reads
without color. `empty="blank"` drops the empty cells entirely instead of dimming them, for surfaces where the outline
reads as noise. Auto packing is the default because a near-square honeycomb is the recognizable form. The unit is the
cell, and its size never changes with value — the count varies, the geometry doesn't — which is what keeps this honest
area-filling _occupancy_, distinct from a `PictogramRow` counting unlike things. Above sixty cells, unit counting stops
being countable, so the chart emits a dev warning and the docs steer to `Progress`. A value past the total fills every
cell, but the accessible name still states the true number — occupancy is never silently clipped.

## 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 /
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 or press `Escape`.
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"). |
| `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).