# Ring progress

A built-in tag for a circular (donut) progress ring. Pass `sections` as a JSON
array of `{value, color}` objects — one arc per object — and optionally set a
center `label`, the `size` and `thickness` in px, and `roundCaps` for rounded arc
ends.

Use it as `{% ringprogress %}` in Markdown, or call it from
Python logic (loops, snippets) via `component('aardvark', 'ringprogress', …)`.

## Demonstrations

### Single section

The minimal form — one section and a center label:



<br>

Source: Markdown

```aardvark
{% ringprogress sections='[{"value":40,"color":"cyan"}]' label="40%" %}
```


Source: Python

```python
component('aardvark', 'ringprogress',
          sections='[{"value":40,"color":"cyan"}]', label='40%')
```



### Multiple sections

Each object in `sections` is one colored arc; the values stack around the ring.
`size` sets the ring's width and height in px:



<br>

Source: Markdown

```aardvark
{% ringprogress sections='[{"value":40,"color":"cyan"},{"value":15,"color":"orange"},{"value":15,"color":"grape"}]' label="70%" size=140 %}
```


Source: Python

```python
component('aardvark', 'ringprogress', label='70%', size=140, sections=(
    '[{"value":40,"color":"cyan"},'
    '{"value":15,"color":"orange"},'
    '{"value":15,"color":"grape"}]'))
```



### Thickness and rounded caps

`thickness` sets the arc width in px; `roundCaps` rounds the ends of each arc:



<br>

Source: Markdown

```aardvark
{% ringprogress sections='[{"value":65,"color":"teal"}]' label="65%" thickness=16 roundCaps=true size=140 %}
```


Source: Python

```python
component('aardvark', 'ringprogress',
          sections='[{"value":65,"color":"teal"}]',
          label='65%', thickness=16, roundCaps=True, size=140)
```



## With other components

Pair a ring with a caption underneath, grouped in a centered
`{% stack %}`:





Tests passing




<br>

Source: Markdown

```aardvark
{% stack align="center" gap="xs" %}
{% ringprogress sections='[{"value":82,"color":"teal"}]' label="82%" size=120 %}
{% text size="sm" c="dimmed" %}Tests passing{% endText %}
{% endStack %}
```


Source: Python

```python
component('aardvark', 'ringprogress',
          sections='[{"value":82,"color":"teal"}]', label='82%', size=120)
component('aardvark', 'text', size='sm', c='dimmed', children='Tests passing')
```



## Attributes

| Attribute | Valid values | Description |
| --- | --- | --- |
| `sections` | A JSON array of `{value, color}` objects | **Required.** One arc per object. Invalid JSON degrades to a build-time HTML comment. |
| `size` | A number of px | Width and height of the ring. Defaults to Mantine's 120. |
| `thickness` | A number of px | Arc thickness. Defaults to Mantine's ~12. |
| `roundCaps` | bool (default `false`) | Round the ends of each arc. |
| `label` | Any string | Text shown in the center of the ring. |


## CSS Selectors

Each `ringprogress` carries `data-aardvark-island="RingProgress"` on its wrapper, and Mantine exposes its parts as `mantine-RingProgress-*` classes — target either to style it from your theme CSS.


```css
[data-aardvark-island="RingProgress"] {
  /* style every ringprogress on the page */
}

.mantine-RingProgress-root {
  /* the root part */
}

.mantine-RingProgress-svg {
  /* the svg part */
}

.mantine-RingProgress-curve {
  /* the curve part */
}

.mantine-RingProgress-label {
  /* the label part */
}
```


## Injecting Attributes

`attr={…}` forwards raw HTML attributes (including event handlers) straight onto the rendered element.



<br>

Source: Markdown

```aardvark
{% ringprogress sections='[{"value":40,"color":"cyan"}]' label="40%" attr={'onclick': '''
const value = this.innerText;
console.log('attr demo value:', value);
alert(value);
'''} %}
```


Source: Python

```python
component('aardvark', 'ringprogress',
          sections='[{"value":40,"color":"cyan"}]', label='40%', attr={'onclick': '''
const value = this.innerText;
console.log('attr demo value:', value);
alert(value);
'''})
```