# DonutChart

Shares of a whole with an in-ring total and exact values on inspection.

Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.

## Example

```tsx
"use client";

import { FloodRoot, DonutChart } from "@flood-md/react";
import "@flood-md/react/styles.css";

export function Example() {
  return (
    <FloodRoot>
      <DonutChart label="Traffic sources" totalLabel="Visits" items={[
        {id:"direct", label:"Direct", value:6420},
        {id:"search", label:"Search", value:3720},
        {id:"referrals", label:"Referrals", value:1960}
      ]} />
    </FloodRoot>
  );
}
```

## Design notes

- Pass up to six mutually exclusive categories in display order. Values must be finite and nonnegative. The ring uses their sum as the whole.
- Hover, tap or use arrow keys, Home and End to inspect a category. Its name, exact value and share appear inside the ring. Enable showLegend when readers need the category names before interacting.
- An empty list displays the empty label. All-zero data displays a total of zero and omits percentages. Supply formatValue and formatShare for localized output.

## API reference

| Prop | Values | Default |
| --- | --- | --- |
| `label` | `string` | `Required` |
| `items` | `readonly DonutChartItem[]` | `Required` |
| `totalLabel` | `string` | `"Total"` |
| `emptyLabel` | `string` | `"No data"` |
| `navigationLabel` | `string` | `"Use the arrow keys to explore segments, or Home and End to jump."` |
| `showLegend` | `boolean` | `—` |
| `formatValue` | `(value: number) => string` | `—` |
| `formatShare` | `(share: number) => string` | `—` |
| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |