Ring

Progress in five patterns (an arc, nested goals, steps, a gauge, a spinner) and a ring that shows who is talking.

The ring shows progress: one arc, several nested goals, discrete steps or a gauge. Drive it with progress (or a list of them) from your app.

ring · completing

See every ring pattern live

When to use which pattern

Pattern	`pattern`	When to use it
Completing	`completing`	One task's progress: an arc that fills.
Loading	`loading`	Indeterminate wait: a spinner.
Tracking	`tracking`	Several goals at once: nested activity rings with extra laps.
Stepping	`stepping`	Discrete steps: segments that fill one by one.
Measuring	`measuring`	A reading within a range: a gauge.
Talking	`talking`	Who is talking: a ring round a participant's picture.

talking is a ring round a person's picture, for a call or a group conversation. It thickens outward with their voice and never covers the face; ripples go out while they speak and in while they listen, and an arc circles while they think. SinuaAvatar puts the image in the middle for you (not on React Native yet).

avatar-react.tsx

import { SinuaAvatar } from "@sinua/web/react";
import type { VoiceSource } from "@sinua/core";

// A participant's picture with a ring that shows who is talking: it thickens outward
// with the voice and never covers the face. The ring is decorative; `alt` names the person.
export function Speaker({ voice }: { voice: VoiceSource }) {
  return <SinuaAvatar src="/ada.jpg" alt="Ada" voice={voice} style={{ width: 56 }} />;
}

Props

Every prop, per pattern. Values are your app's data; everything else is style. Defaults can differ per size (20 · 32 · 64).

The ring component is SinuaRing. Pick a look with pattern; each pattern reads the props below. Sizes are engine sizes (20, 32, 64): defaults can differ per size.

Pattern	Mode	Speed	Values (app data)
Completing (`completing`)	`arc`	1×	`progress`
Loading (`loading`)	`spinner`	1×	—
Tracking (`tracking`)	`nested`	1×	`progress`
Stepping (`stepping`)	`segmented`	1×	`progress`, `segment`
Measuring (`measuring`)	`gauge`	1×	`progress`
Talking (`talking`)	`speaker`	1×	—

Completing

pattern: "completing" · mode arc · speed 1× · sizes 20, 32, 64

Prop	Category	Type	Range	Default	Description
`gap`	Appearance	number	0–8 (UI 0–3) x	1	Gap between the indicator and the track, in stroke widths.
`hue`	Appearance	number	0–360 deg	200	Ink hue in degrees; applies once saturation is above 0.
`ink`	Appearance	number	0–1 fraction	1	How present the whole visual is: 1 draws it as the pattern defines it, lower fades everything including its halos. A voice assistant rests below 1 when idle and comes to full ink when it listens.
`saturation`	Appearance	number	0–1 fraction	0	How far the ink moves from grey toward the hue (0 = the grey ink).
`strokeWidth`	Appearance	number	0.01–0.4 (UI 0.02–0.25) fraction	0.085	Stroke width as a fraction of the frame.
`trackOpacity`	Appearance	number	0–1 (UI 0–0.6) fraction	0.18	Opacity of the faint track behind the indicator (0 = none).
`progress`	Inputs	number	0–1 fraction	0	How much of the ring is filled, 0 to 1.

Loading

pattern: "loading" · mode spinner · speed 1× · sizes 20, 32, 64

Prop	Category	Type	Range	Default	Description
`gap`	Appearance	number	0–8 (UI 0–3) x	1	Gap between the indicator and the track, in stroke widths.
`hue`	Appearance	number	0–360 deg	200	Ink hue in degrees; applies once saturation is above 0.
`ink`	Appearance	number	0–1 fraction	1	How present the whole visual is: 1 draws it as the pattern defines it, lower fades everything including its halos. A voice assistant rests below 1 when idle and comes to full ink when it listens.
`saturation`	Appearance	number	0–1 fraction	0	How far the ink moves from grey toward the hue (0 = the grey ink).
`strokeWidth`	Appearance	number	0.01–0.4 (UI 0.02–0.25) fraction	0.085	Stroke width as a fraction of the frame.
`trackOpacity`	Appearance	number	0–1 (UI 0–0.6) fraction	0	Opacity of the faint track behind the indicator (0 = none).

Tracking

pattern: "tracking" · mode nested · speed 1× · sizes 20, 32, 64

Prop	Category	Type	Range	Default	Description
`hue`	Appearance	number	0–360 deg	200	Ink hue in degrees; applies once saturation is above 0.
`hueStep`	Appearance	number	-180–180 (UI -90–90) deg	0	Degrees of hue added per ring (0 = one hue).
`ink`	Appearance	number	0–1 fraction	1	How present the whole visual is: 1 draws it as the pattern defines it, lower fades everything including its halos. A voice assistant rests below 1 when idle and comes to full ink when it listens.
`ringCount`	Appearance	integer	1–4	3	Concentric rings, outermost first.
`saturation`	Appearance	number	0–1 fraction	0	How far the ink moves from grey toward the hue (0 = the grey ink).
`spacing`	Appearance	number	0–2 x	0.25	Gap between rings, in stroke widths.
`strokeWidth`	Appearance	number	0.01–0.4 (UI 0.02–0.25) fraction	0.07	Stroke width as a fraction of the frame.
`trackOpacity`	Appearance	number	0–1 (UI 0–0.6) fraction	0.18	Opacity of the faint track behind the indicator (0 = none).

Advanced props (2)

Prop	Category	Type	Range	Default	Description
`maxLaps`	Appearance	number	1–10	3	The most laps a ring value can draw.
`progress`	Inputs	number[] (1–4, length = `ringCount`)	0–3	[]	Per-ring value; past 1 draws extra laps (up to maxLaps). Also accepted: `progress0`, `progress1`, `progress2`, `progress3`.

Stepping

pattern: "stepping" · mode segmented · speed 1× · sizes 20, 32, 64

Prop	Category	Type	Range	Default	Description
`gap`	Appearance	number	0–8 (UI 0–3) x	0.3333	Visible gap between segments, in stroke widths.
`hue`	Appearance	number	0–360 deg	200	Ink hue in degrees; applies once saturation is above 0.
`ink`	Appearance	number	0–1 fraction	1	How present the whole visual is: 1 draws it as the pattern defines it, lower fades everything including its halos. A voice assistant rests below 1 when idle and comes to full ink when it listens.
`saturation`	Appearance	number	0–1 fraction	0	How far the ink moves from grey toward the hue (0 = the grey ink).
`segmentCount`	Appearance	number	1–24	5	Number of equal segments.
`strokeWidth`	Appearance	number	0.01–0.4 (UI 0.02–0.25) fraction	0.085	Stroke width as a fraction of the frame.
`trackOpacity`	Appearance	number	0–1 (UI 0–0.6) fraction	0.18	Opacity of the faint track behind the indicator (0 = none).
`progress`	Inputs	number	0–1 fraction	0	How many segments are filled, as a fraction 0 to 1.

Advanced props (1)

Prop	Category	Type	Range	Default	Description
`segment`	Inputs	number[] (1–24, length = `segmentCount`)	0–1 fraction	[]	Per-segment fill (0 to 1) when segments fill independently; overrides progress for the segments given.

Measuring

pattern: "measuring" · mode gauge · speed 1× · sizes 20, 32, 64

Prop	Category	Type	Range	Default	Description
`fill`	Appearance	boolean		1	Draw the value bar.
`hue`	Appearance	number	0–360 deg	200	Ink hue in degrees; applies once saturation is above 0.
`ink`	Appearance	number	0–1 fraction	1	How present the whole visual is: 1 draws it as the pattern defines it, lower fades everything including its halos. A voice assistant rests below 1 when idle and comes to full ink when it listens.
`marker`	Appearance	boolean		0	Draw a marker dot at the value.
`saturation`	Appearance	number	0–1 fraction	0	How far the ink moves from grey toward the hue (0 = the grey ink).
`strokeWidth`	Appearance	number	0.01–0.4 (UI 0.02–0.25) fraction	0.085	Stroke width as a fraction of the frame.
`sweep`	Appearance	number	90–330 deg	270	Total arc of the gauge in degrees; the opening is centred at the bottom.
`trackOpacity`	Appearance	number	0–1 (UI 0–0.6) fraction	0.18	Opacity of the faint track behind the indicator (0 = none).
`progress`	Inputs	number	0–1 fraction	0	The gauge value, 0 to 1.

Advanced props (1)

Prop	Category	Type	Range	Default	Description
`gap`	Appearance	number	0–8 x	1	Gap at the gauge's value end, in stroke widths.

Talking

pattern: "talking" · mode speaker · speed 1× · sizes 20, 32, 64

Prop	Category	Type	Range	Default	Description
`avatarGap`	Appearance	number	0–0.05 (UI 0–0.04) fraction	0.012	Space between the avatar's edge and the ring, as a fraction of the frame.
`hue`	Appearance	number	0–360 deg	200	Ink hue in degrees; applies once saturation is above 0.
`idleOpacity`	Appearance	number	0–1 fraction	0.35	The ring's opacity when nobody is speaking (0 = hidden until there's a voice).
`ink`	Appearance	number	0–1 fraction	1	How present the whole visual is: 1 draws it as the pattern defines it, lower fades everything including its halos. A voice assistant rests below 1 when idle and comes to full ink when it listens.
`innerRadius`	Appearance	number	0.1–0.44 (UI 0.2–0.42) fraction	0.34	Radius of the avatar the ring surrounds, as a fraction of the frame; nothing is drawn inside it.
`saturation`	Appearance	number	0–1 fraction	0	How far the ink moves from grey toward the hue (0 = the grey ink).
`thickness`	Appearance	number	0.004–0.1 (UI 0.008–0.06) fraction	0.022	The ring's resting stroke width, as a fraction of the frame.
`flow`	Motion	number	-1–1	0	Ripples outside the ring: +1 travel outward (giving out, speaking), -1 come inward (taking in, listening), 0 none. The voice states set it.
`rippleCount`	Motion	integer	0–4	2	How many ripples travel at once when flow is on.
`shimmer`	Motion	number	0–1 fraction	0	A brighter arc that circles the ring (thinking, connecting); 0 = off.
`reach`	Energy	number	0–0.12 fraction	0.04	How much thicker the ring grows at full voice, outward only, as a fraction of the frame.

On this page