A React Native radial chart for mobile gauges, progress rings, and circular data with customizable arcs and labels.
RadialChartruns on the UI thread. React renders the parts once; data changes, the sweep-in, the press highlight and the tooltip all update through Reanimated shared values without re-rendering. Rendering a chart requires the optionalreact-native-skiapeer (>=3.0.0).
import { RadialChart } from 'heroui-native-pro';<RadialChart data={...} labelKey="..." valueKey="...">
<RadialChart.Bar />
<RadialChart.Tooltip />
</RadialChart>data, one per ring), the fields holding each ring's label, value and optional color, and the layout: value domain, angles, radii and ring sizes. Owns the canvas, the press gesture and the animation settings for every part. Fills the parent's width as a square by default; change the size with className.0 innermost, each over an optional track. While a ring is pressed, the others dim.Center labels and side legends are regular views composed around the chart (see Center content).
The domain is [0, "auto"] by default: the largest value sweeps the full circle.
<RadialChart data={DATA} labelKey="name" valueKey="value" className="w-[200px]">
<RadialChart.Bar />
</RadialChart>colorKey names the field holding each ring's color. It is optional: rows without a color take the theme chart colors chart-1 … chart-5 in turn.
const DATA = [
{ name: 'Calories', value: 200, color: '#a78bfa' },
{ name: 'Steps', value: 350, color: '#8b5cf6' },
{ name: 'Exercise', value: 250 }, // theme chart color
];
<RadialChart data={DATA} labelKey="name" valueKey="value" colorKey="color">
<RadialChart.Bar />
</RadialChart>;Fix the domain so the sweep maps to a percentage. A single row with a large innerRadius reads as a progress ring.
<RadialChart
data={[{ name: 'Score', value: 78 }]}
labelKey="name"
valueKey="value"
domain={[0, 100]}
innerRadius="72%"
barSize={14}
className="w-[220px]"
>
<RadialChart.Bar cornerRadius={14} />
</RadialChart>Angles are in degrees counter-clockwise from 3 o'clock, so 90 is 12 o'clock. The default startAngle={90} and endAngle={-270} make the domain a full clockwise turn from the top. For a half-circle gauge that opens downward:
<RadialChart
data={DATA}
labelKey="name"
valueKey="value"
domain={[0, 100]}
startAngle={180}
endAngle={0}
>
<RadialChart.Bar />
</RadialChart>barSize sets each ring's thickness and barGap the space between rings, in pixels. Rings stack outward from innerRadius. Pass barGap="auto" to spread them evenly from innerRadius to outerRadius instead.
<RadialChart
data={DATA}
labelKey="name"
valueKey="value"
innerRadius="30%"
outerRadius="100%"
barSize={12}
barGap="auto"
>
<RadialChart.Bar />
</RadialChart>RadialChart.Bar draws the whole domain behind each ring as a track in the theme default color. Pass trackColor to change it or background={false} to hide it. cornerRadius={0} gives square ring ends.
<RadialChart.Bar background={false} cornerRadius={0} />Pass a new data array and the rings glide to their new sweeps. Always pass a new array: changes made to the same array in place are not detected.
<RadialChart
data={presets[preset]}
labelKey="name"
valueKey="value"
animate={{ type: 'spring' }}
>
<RadialChart.Bar />
</RadialChart>animate is true by default (300 ms timing). Pass a timing or spring config, or false. animation="disable-all" turns off every animation in the chart: the data-change transition, the sweep-in and the press highlight.
animateIn sweeps the rings in from their start on mount (true is 700 ms; a number sets the duration). Change resetKey to replay it.
const [replay, setReplay] = useState(0);
<RadialChart
data={DATA}
labelKey="name"
valueKey="value"
animateIn
resetKey={replay}
>
<RadialChart.Bar />
</RadialChart>;Long-press a ring (100 ms by default) to select it; anywhere along its track counts. The other rings dim to dimOpacity (default 0.4), and RadialChart.Tooltip shows the ring's label and value at the end of the ring.
<RadialChart data={DATA} labelKey="name" valueKey="value">
<RadialChart.Bar dimOpacity={0.3} />
<RadialChart.Tooltip />
</RadialChart>To react on the JS thread, use onSelect. It fires when the pressed ring changes, and with null when the press ends.
<RadialChart
data={DATA}
labelKey="name"
valueKey="value"
onSelect={(event) => setActive(event?.row ?? null)}
>selection={{ activateAfter: 200 }} changes the press delay; selection={false} turns inspection off.
Build the content from ChartTooltipLabel and ChartTooltipValue. They show the pressed row's fields and re-render only when the selection moves to another ring. Pass the root's labelKey field as xKey. With a worklet format (or none), their text is written from the UI thread instead; see Tooltip text on the UI thread.
import { ChartTooltipLabel, ChartTooltipValue } from 'heroui-native-pro';
<RadialChart.Tooltip className="rounded-xl bg-surface p-2">
<ChartTooltipLabel xKey="name" className="text-xs text-muted" />
<ChartTooltipValue dataKey="value" className="text-sm text-foreground" />
</RadialChart.Tooltip>;Overlay a view on the chart for a headline number. Mark it pointerEvents="none" so it does not block the press gesture.
<View className="w-[200px]">
<RadialChart data={DATA} labelKey="name" valueKey="value">
<RadialChart.Bar />
</RadialChart>
<View
pointerEvents="none"
className="absolute inset-0 items-center justify-center"
>
<Text className="text-sm font-semibold text-foreground">700 kcal</Text>
</View>
</View>import { Card } from 'heroui-native';
import { RadialChart } from 'heroui-native-pro';
import { Text, View } from 'react-native';
const DATA = [{ name: 'Storage', value: 72 }];
export default function StorageGauge() {
return (
<View className="flex-1 justify-center px-5">
<Card>
<Card.Header>
<Card.Title>Storage Used</Card.Title>
</Card.Header>
<Card.Body className="items-center">
<View className="w-2/3">
<RadialChart
data={DATA}
labelKey="name"
valueKey="value"
domain={[0, 100]}
innerRadius="72%"
barSize={14}
animateIn
selection={false}
>
<RadialChart.Bar />
</RadialChart>
<View
pointerEvents="none"
className="absolute inset-0 items-center justify-center"
>
<Text className="text-3xl font-bold text-foreground">72%</Text>
<Text className="text-sm text-muted">of 128 GB</Text>
</View>
</View>
</Card.Body>
</Card>
</View>
);
}The chart deliberately stays left-to-right in RTL layouts: everything inside the canvas is drawn by Skia in physical coordinates, and angular progress conventionally sweeps the same way in RTL locales too. Pair the chart with a text label or summary when the values matter to screen reader users.
| prop | type | default | description |
|---|---|---|---|
data | Row[] | - | One row per ring, row 0 innermost. A new array animates. |
labelKey | keyof Row | - | Field holding each ring's label (string or number), shown by the tooltip. |
valueKey | keyof Row | - | Field holding each ring's value. |
colorKey | keyof Row | - | Field holding each ring's color. Rows without one take chart-1 … chart-5. |
domain | [number | 'auto', number | 'auto'] | [0, 'auto'] | Value range the full sweep covers. 'auto' ends fit the data. |
startAngle | number | 90 | Start angle, degrees counter-clockwise from 3 o'clock (90 is 12 o'clock). |
endAngle | number | -270 | End angle. The default makes the domain a full clockwise turn. |
innerRadius | number | '${number}%' | '40%' | Inner bound of the rings, in pixels or as a percentage of the chart radius. |
outerRadius | number | '${number}%' | '100%' | Outer bound of the rings, in pixels or as a percentage of the chart radius. |
barSize | number | 10 | Ring thickness in pixels. |
barGap | number | 'auto' | 4 | Gap between rings in pixels; 'auto' spreads them from inner to outer radius. |
animateIn | boolean | number | false | Sweeps the rings in on mount; true is 700 ms, a number sets the duration. |
resetKey | unknown | - | Changing it replays animateIn. |
animate | boolean | ChartTransition | true | Data-change animation ({ type: 'timing' | 'spring', ...config }). |
animation | 'disable-all' | - | "disable-all" turns off every animation in the chart. |
selection | { activateAfter?: number } | false | { activateAfter: 100 } | Press-to-inspect; false turns it off. |
onSelect | (event: { index: number; row: Row } | null) => void | - | Called on the JS thread when the pressed ring changes; null when it ends. |
className | string | w-full aspect-square | Root view class. Set the size here. |
children | ReactNode | - | Chart parts. |
| prop | type | default | description |
|---|---|---|---|
background | boolean | true | Draws the whole domain behind each ring as a track. |
trackColor | string | theme default | Track color. |
cornerRadius | number | 12 | Rounds the ring ends when greater than 0; 0 gives square ends. |
dimOpacity | number | 0.4 | Opacity of the other rings while one is pressed. 1 disables dim. |
| prop | type | default | description |
|---|---|---|---|
dataKey | string | root valueKey | Field whose value the default content shows. |
format | (value: number) => string | - | Formats the default value. Runs on the JS thread. |
placement | 'top' | 'bottom' | away from the center | Preferred side of the ring end; flips when there is no room. Without it, above the upper half of the chart and below the lower half. |
gap | number | 12 | Space between the anchor point and the tooltip. |
className | string | - | Tooltip view class. Replaces the default pill when children is set. |
children | ReactNode | - | Custom content (ChartTooltipLabel, ChartTooltipValue). |