# Donut
> Donut chart that sweeps in clockwise; hovering or arrowing to a segment pops it outward and rolls its share into the centre.
- Element: `<hf-donut>`
- React: `import { HfDonut } from "@/components/lumesec/hf-donut"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-donut.json
- Page: https://elements.lumesec.ai/components/pixel-hd/donut



Live preview: https://elements.lumesec.ai/view/hf-donut

```html
<hf-donut data="Code:42,Writing:23,Analysis:18,Other:17" total="1,284" label="Conversations"></hf-donut>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-donut
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-donut.json
```

## Usage

React:

```tsx
import { HfDonut } from "@/components/lumesec/hf-donut";

export function Example() {
  return (
    <HfDonut data="Code:42,Writing:23,Analysis:18,Other:17" total="1,284" label="Conversations" />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-donut.js"></script>

<hf-donut data="Code:42,Writing:23,Analysis:18,Other:17" total="1,284" label="Conversations"></hf-donut>
```

## Behaviour

Sweeps in clockwise. Hovering a segment or legend row pops it outward and rolls its share into the middle; arrow keys work too.

## API reference

### Attributes

| Attribute | React prop | Type     | Default                                   | Description                                                                                             |
| --------- | ---------- | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `data`    | `data`     | `string` | `Code:42,Writing:23,Analysis:18,Other:17` | Comma-separated `Label:value` pairs. Values are relative and shown as rounded percentages of their sum. |
| `label`   | `label`    | `string` | `Usage by task`                           | Text in the centre and the start of the `aria-label`.                                                   |
| `total`   | `total`    | `string` | —                                         | Text in the centre when no segment is focused. Defaults to the sum of the values.                       |

### Properties

| Property           | Type                                  | Description                         |
| ------------------ | ------------------------------------- | ----------------------------------- |
| `data` (read-only) | `Array<{ label: string, v: number }>` | Segments parsed from the attribute. |

## Keyboard

| Keys                   | Action                                |
| ---------------------- | ------------------------------------- |
| ArrowRight / ArrowDown | Focus the next segment, wrapping.     |
| ArrowLeft / ArrowUp    | Focus the previous segment, wrapping. |

## Accessibility

* The canvas has `role="img"`, `tabindex="0"` and an `aria-label` listing each segment percentage.
* The centre text is not a live region.
* Legend rows react to pointer hover only. Moving focus away from the canvas clears the highlight.
* Reduced motion: the donut appears without the sweep and the centre text swaps without rolling; the segment pop still eases.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--lumesec` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg` and `--ui-muted`.

## Notes

* Colours cycle through accent, ok, warn, danger and muted; a sixth segment reuses the accent colour.
* Attributes are read once on connect and are not observed.
* The chart is fixed at 176 × 176 px.