# Goal rings
> Up to three concentric goal rings with glowing heads; progress past the goal laps the ring in a brighter tint and throws sparks.
- Element: `<hf-rings>`
- React: `import { HfRings } from "@/components/lumesec/hf-rings"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-rings.json
- Page: https://elements.lumesec.ai/components/pixel-hd/rings



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

```html
<hf-rings rings="Messages:36/50,Tokens:410/900,Agents:13/10"></hf-rings>
```

## 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-rings
```

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

## Usage

React:

```tsx
import { HfRings } from "@/components/lumesec/hf-rings";

export function Example() {
  return (
    <HfRings rings="Messages:36/50,Tokens:410/900,Agents:13/10" />
  );
}
```

HTML:

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

<hf-rings rings="Messages:36/50,Tokens:410/900,Agents:13/10"></hf-rings>
```

## Behaviour

Three progress rings with glowing heads. Going past the goal laps the ring in a brighter colour and throws sparks at the top. Hover a ring or a legend row to isolate it.

## API reference

### Attributes

| Attribute | React prop | Type     | Default                                      | Description                                                                                                                             |
| --------- | ---------- | -------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `rings`   | `rings`    | `string` | `Messages:36/50,Tokens:410/900,Agents:13/10` | Comma-separated `Name:current/goal` entries; only the first three are used. Observed: changes rebuild the legend and animate the rings. |

### Properties

| Property            | Type                                                 | Description                      |
| ------------------- | ---------------------------------------------------- | -------------------------------- |
| `items` (read-only) | `Array<{ name: string, cur: number, goal: number }>` | Rings parsed from the attribute. |

## Accessibility

* The canvas has `role="img"` and an `aria-label` giving each ring as a percentage of its goal, for example `Messages 72%, Tokens 46%, Agents 130%`.
* The legend shows each current value and goal as text.
* Isolating a ring works by pointer hover only; legend rows are not focusable.
* Reduced motion: the rings show their final progress without the staggered fill and no sparks are drawn; the hover dimming still fades.

## 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

* Rings use the accent, ok and warn colours from the outside in.
* Progress is drawn up to twice the goal; the second lap uses a brighter tint.
* The canvas is fixed at 172 × 172 px.