# DicePips (/docs/charts/dice-pips)

DicePips answers "what is this small count or severity?" the way dice do — a face you read without counting. The brain
subitizes the canonical 1–6 patterns instantly. Zero is an empty face (zero, not missing); above six there is no
subitizable pattern, so the face shows the exact numeral rather than inventing a seven-pip layout. The face never
pretends.

```tsx
<span className="inline-flex gap-3 items-center">
  <DicePips value={1} size={20} title="one" />
  <DicePips value={2} size={20} title="two" />
  <DicePips value={3} size={20} title="three" />
  <DicePips value={4} size={20} title="four" />
  <DicePips value={5} size={20} title="five" />
  <DicePips value={6} size={20} title="six" />
</span>
```

## Install

```tsx
import { DicePips } from "@microcharts/react/dice-pips";

<DicePips value={4} title="Severity" />
```

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** — a severity or rating 0–6 in a cell, an at-a-glance small count in a sentence, or an incident-severity
  badge.
- **Avoid for** — counts above six (TallyMarks), magnitudes (MiniBar), or proportions (Progress).


## Variants

```tsx
<DicePips value={5} face={false} />
<DicePips value={9} />
```

## Edge cases

```tsx
<DicePips value={0} />
```

```tsx
<DicePips value={-2} />
```

```tsx
<DicePips value={3.6} />
```


## Why this default

The face outline keeps a lone die legible on any surface, so it is on by default; `face={false}` drops it for repeated
table columns where the header already frames the column. Six is the ceiling because pip patterns above six are not
subitizable — asking the reader to count invented pips would be slower than reading a number, so the chart refuses and
shows the numeral instead. That numeral fallback is the documented honesty rule, shown live at `value={9}`.

## Accessibility

The accessible name states the value against its range — **"4 out of 6."** — and drops the frame to just the exact
number once past six (**"9."**). Zero reads "0 out of 6." (a real zero), and an invalid value reads "No data." The
interactive entry pops the pips into place on change (a short scale-up with a per-pip stagger, skipped under
`prefers-reduced-motion`) and announces the new face through a polite live region; the pips are one value, so there is
no cursor to move.

This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it
and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared
[interaction contract](/docs/accessibility#one-interaction-contract).

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `value` (required) | `number` | Integer 0–6 (rounded); above 6 shows a numeral. |
| `face` | `boolean` | Draw the die outline (default true). |

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).