# RadialChart

Radial bars and gauges, with tracks, labels along the arc and a center value.

```ehtml Example
import { RadialChart } from "@elements/ui/chart-radial";
import type { ChartConfig } from "@elements/ui/chart";

<RadialChart data={rows} {config} value="visitors" name="browser" innerRadius={30} background />

<!-- a gauge -->
<RadialChart data={[{ task: "done", done: 64 }]} {config} value="done" name="task"
             max={100} startAngle={90} endAngle={-270} innerRadius="70%" background
             cornerRadius={12} centerValue="64%" centerLabel="complete" />
```

## Parts

| Part | What it is |
|---|---|
| `RadialChart` | The template. One ring of arcs per row. |
| `.chart-radial-bar` | One arc (an SVG path) and its own hit target. |
| `.chart-radial-track` | The background arc behind a bar, with background. |
| `.chart-radial-ring` | A grid circle; .is-filled rings draw a track. |
| `.chart-center` | Center text: .chart-center-value and .chart-center-label. |
| `.chart` | The figure. Declares `--color-<key>` for each config entry; keeps a 16:9 box unless sized by class. |
| `.chart-plot` | The focusable plot area holding the SVG; one tab stop. |
| `.chart-tooltip` | The tooltip: heading, one row per item with swatch, name and value, optional footer. |
| `.chart-legend` | The legend row; .chart-legend-item per series, a button with legend toggle. |
| `.chart-table` | The data as a table, visually hidden unless showTable. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `data` | `Row[]` | (required) | One ring per row, the first innermost. A row's fill field colors its arc. |
| `config` | `ChartConfig` | (required) | The chart config: per data key a label, a color (any CSS color, usually var(--chart-N)) or a theme { light, dark }, and an optional icon; legendType and tooltipType; strokeDasharray and strokeOpacity dash and fade a line or an area's edge. Each key becomes `--color-<key>` on the chart. |
| `value` | `string \| string[]` | (required) | The value field. Several sit side by side in each ring, or stack along it. |
| `name` | `string` | `""` | The name field: tooltip and legend names and colors through the config. |
| `stack` | `boolean` | `false` | Stack the value keys end to end along the arc. |
| `stackOffset` | `"none" \| "expand"` | `"none"` | expand stacks every row to the end angle, so the arc reads shares. |
| `reverseStackOrder` | `boolean` | `false` | Stack the last value key first, so the first ends the arc; the legend and tooltip keep value order. |
| `innerRadius` | `number \| string` | `0` | px, or a percent of the largest radius that fits. |
| `outerRadius` | `number \| string` | `"80%"` | px, or a percent. |
| `startAngle` | `number` | `0` | Degrees, counter-clockwise from three o'clock. |
| `endAngle` | `number` | `360` | Where the largest value (or max) ends. 90 to -270 runs clockwise from twelve. |
| `max` | `number` | `0` | The value that fills the sweep; 0 uses the largest value or stack. |
| `angleAxis` | `{ series?: string[]; max?: number }[]` | `[]` | Several value scales, each for the keys it names; the first scales the rest. |
| `radiusAxis` | `{ series?: string[]; reversed?: boolean }[]` | `[]` | Ring orders, each for the keys it names; reversed puts the first row outermost. |
| `hide` | `boolean \| string[]` | `false` | Value keys not drawn and left out of the tooltip; true for all. |
| `layout` | `"radial" \| "centric"` | `"radial"` | centric makes each row a wedge of the turn whose value reaches out from innerRadius. |
| `maxBarSize` | `number` | `0` | The most a computed ring may be thick, px. |
| `activeShape` | `boolean` | `false` | Outline the active ring. |
| `minPointSize` | `number` | `0` | The least angle, in degrees, of any bar whose value is present, zero included. |
| `forceCornerRadius` | `boolean` | `false` | A bar too short for its corners draws as a round dot. |
| `cornerIsExternal` | `boolean` | `false` | Round the ends outside the bar, past its start and end angles. |
| `margin` | `{ top?, right?, bottom?, left? }` | `{}` | Space around the plot in px. |
| `cx, cy` | `number \| string, number \| string` | `"50%", "50%"` | The center of the chart: px from the left and top edges, or a percentage of the plot. |
| `barSize` | `number` | `0` | Fixed ring thickness, px; 0 computes it. |
| `barGap` | `number` | `4` | px between side-by-side arcs in a ring. |
| `barCategoryGap` | `number \| string` | `"10%"` | Space on each side of a ring's arcs. |
| `cornerRadius` | `number` | `0` | Rounded arc ends, px. |
| `minAngle` | `number` | `0` | The least angle of a bar with a value, degrees. |
| `separator` | `boolean` | `false` | A gap between stacked arcs in the surface color. |
| `background` | `boolean` | `false` | A track behind each arc over the whole sweep. |
| `grid` | `boolean \| { radii?: number[]; radialLines?: boolean; filled?: boolean }` | `false` | Circles through the rings or at radii; filled draws the first in the muted surface and the rest in the background, so two radii make a track. |
| `labels` | `boolean \| { position?: "insideStart" \| "insideEnd" \| "end"; key?: string; formatter?: (value, row) => string }` | `false` | Text along each arc. |
| `centerValue` | `string` | `""` | Large text in the center. |
| `centerLabel` | `string` | `""` | Small text under it. |
| `tooltip` | `boolean \| { indicator?: "dot" \| "line" \| "dashed"; hideLabel?: boolean; hideIndicator?: boolean; color?: string; labelKey?: string; nameKey?: string; labelFormatter?: (label, row) => string; formatter?: (value, key, row) => string; footer?: (row) => string; footerLabel?: string; unit?: string; defaultIndex?: number; cursor?: boolean; filterNull?: boolean; trigger?: "hover" \| "click"; active?: boolean; position?: { x?, y? }; reverseDirection?: { x?, y? }; itemSorter?: "name" \| "value" \| "key" \| (item) => number \| string; includeHidden?: boolean; animationDuration?: number; animationEasing?: string \| (t) => number; isAnimationActive?: boolean }` | `true` | The tooltip: false turns it off; an object sets the indicator, hides the heading or swatches, takes names and headings from other keys, formats them, adds a footer line, or turns off the hover cursor. More options: trigger click (a click shows it and it stays), active (always or never shown), position (a fixed spot), reverseDirection, itemSorter and includeHidden. |
| `legend` | `boolean \| { position?: "top" \| "bottom" \| "left" \| "right" \| "center" \| "insideTop" \| "insideBottom" \| "insideLeft" \| "insideRight" \| "insideTopLeft" \| "insideTopRight" \| "insideBottomLeft" \| "insideBottomRight" \| { x, y }; offset?: number; iconSize?: number; verticalAlign?: "top" \| "middle" \| "bottom"; align?: "left" \| "center" \| "right"; layout?: "horizontal" \| "vertical"; iconType?: "square" \| "rect" \| "circle" \| "line" \| "plainline" \| "diamond" \| "triangle" \| "cross" \| "star" \| "wye" \| "none"; formatter?: (name, key) => string; itemSorter?: "name" \| "key" \| (item) => number \| string; hideIcon?: boolean; nameKey?: string; toggle?: boolean }` | `false` | The legend: above or below the plot, or beside it with verticalAlign middle; position puts it beside the plot, over it at an inside spot or the center, or at a point, offset moves it, iconSize sizes the swatch; align, a vertical layout, the swatch shape (iconType), a name formatter and an itemSorter; names from another key; toggle makes each item a button that hides its series. |
| `active` | `number` (two-way) | `-1` | The active item index. Hover and the arrow keys move it; when the pointer leaves it returns to the value it had. |
| `hidden` | `string[]` (two-way) | `[]` | Series keys not drawn. They stay in the legend, where a toggle legend shows them again. |
| `label` | `string` | `"Radial chart"` | The chart's accessible name and its table's caption. |
| `animate` | `boolean` | `true` | Marks enter with motion and move to new values. Off under prefers-reduced-motion. |
| `animation` | `{ begin?: number; duration?: number; easing?: string \| (t) => number; matchBy?: "index" \| "append" \| (item, index) => key; interpolate?: (items, t) => items; newValues?: boolean }` | `{}` | Times the entry and the move to new data. matchBy pairs old and new items by position or by a key, matchByDataKey(field) from the chart package; interpolate draws every frame of a change from the paired items and the eased time; newValues false shows an unpaired new point at once. |
| `showTable` | `boolean` | `false` | Show the chart's data table under the plot. The table is always in the accessibility tree. |
| `class` | `string` | `""` | Classes on the figure. Size the chart here: it keeps a 16:9 box unless given a height or aspect-ratio. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Any other attributes for the figure: id, data-testid, aria-\*. |
| `syncId` | `string` | `""` | Charts with the same syncId share the active item and its tooltip. |
| `syncMethod` | `"index" \| "value"` | `"index"` | Match the shared item by position, or by its category or name. |
| `onActiveChange` | `(index: number) => void` | `() => {}` | The user moved the active item (hover, leave or keys). |
| `onItemClick` | `(index: number) => void` | `() => {}` | A click or tap on an item, with its index. |
| `onHiddenChange` | `(hidden: string[]) => void` | `() => {}` | A legend toggle changed hidden. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | Focuses the chart (one tab stop) and shows the tooltip for the item the keys last reached, else the active item, else the first. |
| `ArrowRight / ArrowDown` | Next item. The same under dir=rtl: the plot is not mirrored, so keys follow the screen. |
| `ArrowLeft / ArrowUp` | Previous item. |
| `Home / End` | First and last item. |
| `Escape` | Hides the tooltip. In a dialog, the dialog stays open until the next Escape. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-chart` | `"bar" \| "line" \| "area" \| "pie" \| "radar" \| "radial"` | figure |
| `data-state` | `"open" \| "closed"` | .chart-tooltip |
| `data-index` | the item index | .chart-hit and pie, radial marks |
| `data-series` | the series key | marks |
| `data-resizing` | present while the chart redraws for a new size | figure |
| `data-entered` | present once the entry motion is over | figure |
| `aria-pressed` | true \| false | .chart-legend-item (toggle) |

## Accessibility

- The plot is one tab stop: role=group, aria-roledescription=chart, named by label, described by the data table.
- The SVG is aria-hidden; a screen reader gets the data from the table, which every chart renders.
- Arrow keys move through the items and each move is announced in a polite live region, for example "February: Desktop 305, Mobile 200".
- Identity is never color alone: a legend for two or more series and labels on the tooltip rows.
- Legend toggles are buttons with aria-pressed.

## See also

- [Chart](chart): What every chart shares: the config and its colors, the tooltip, the legend, the palette and the data table.
- [BarChart](chart-bar): Vertical, horizontal, stacked and grouped bars with tooltip, legend and labels.
- [LineChart](chart-line): Lines over categories with dots, curves, labels and a crosshair tooltip.
- [AreaChart](chart-area): Filled areas, stacked or expanded, solid or gradient, with a crosshair tooltip.
- [PieChart](chart-pie): Pie and donut charts with labels, a center value, an active slice and stacked rings.
- [RadarChart](chart-radar): Values on radial axes, one polygon per series, over a polygon or circle grid.