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

DicePips prints a small count as a die face: five pips for `5`, an empty face for `0`. The canonical 1–6 patterns are
subitizable, so you read them without counting. Zero means zero, not missing data. Above six there is no pattern to
subitize, so the face shows the exact numeral instead of inventing a seven-pip layout.

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

## Try it

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

<DicePips
  value={4}
/>
```

## When to use it

Use it for a severity or rating 0–6 in a cell, a small count in a sentence, or an incident-severity badge. For counts
above six use TallyMarks, for magnitudes MiniBar, and for proportions Progress.

## Sizing

**pips-only for dense columns**

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

**above 6 shows the exact numeral — no invented pattern**

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

## Variants

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

The face outline is on by default because it keeps a lone die legible on any surface. `face={false}` drops it for a
repeated table column, where the header already frames the column. The second demo is the numeral fallback at
`value={9}`.

## Edge cases

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

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

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

## Four homes

**In a sentence**

```tsx
<p>
  Incident severity{" "}
  <span className="mc-inline">
    <DicePips value={4} summary={false} />
  </span>{" "}
  — rated 4 of 6, elevated but not critical.
</p>
```

**In a table cell**

```tsx
<td>
  <DicePips value={4} />
</td>
```

**In a KPI card**

```tsx
<div className="kpi">
  <span className="figure">4</span>
  <span className="unit">of 6</span>
  <DicePips value={4} />
</div>
```

**In a tab header**

```tsx
<button className="tab">
  INC-142 <DicePips value={4} />
</button>
```

## Accessibility

The accessible name states the value against its range: **"4 out of 6."** Past six it drops the range and gives the
number alone (**"9."**). Zero reads "0 out of 6." 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). |
| `size` | `number` | Die square edge in viewBox units (default 16). |

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