Ring Progress

A circular progress indicator rendered via CSS conic-gradient masked into a donut shape. Progress advances clockwise from 12 o'clock. Sets role="progressbar" with aria-valuenow/min/max. Apply to a <div>.

Props

Prop	Type	Default	Description
`value`	`ValueOrState<number>`	`0`	Progress percentage 0–100.
`color`	`ValueOrState<ThemeColor>`	`"primary"`	Theme color for the filled arc.
`trackColor`	`ValueOrState<ThemeColor>`	`"neutral"`	Theme color for the background track.
`size`	`number`	`16`	Diameter in `themeSpacing` units (e.g. `16` → `4em`).
`thickness`	`number`	`0.25`	Ring stroke as a fraction of the radius. 0 = no ring, 0.5 = solid disc.

Example

import { toState } from "@domphy/core";
import { ringProgress } from "@domphy/ui";

const progress = toState(72);

const App = {
  div: null,
  $: [ringProgress({ value: progress, color: "success", size: 20 })],
};

Customization

Must see the source of patch at the bottom of each patch page to understand the structure then code it still code as html native element.

There are four levels of customization, in increasing order of effort:

Patch props. Each patch exposes a small, stable set of props—typically fewer than five. Lowest friction.
Context attributes. Use dataTone, dataSize, and dataDensity on a container to shift tone, size, or density for an entire subtree without touching individual elements.
Inline override. Native-wins merge strategy: any property set directly on the element overrides the patch value.
Create a variant. Clone a similar patch and edit it. Use this only when you need a reusable custom version.

Formulas

Unit - U = fontSize / 4 - convert final values with themeSpacing(n).

Size - n = intrinsic text lines, w = wrapping level, d = density factor:

height        = (n * 6 + 2 * d * w) * U
paddingBlock  = d * w * U
paddingInline = ceil(3 / w) * d * w * U
radius        = d * w * U

Base density d = 1.5:

U	w=0	w=1	w=2	w=3
height (`n = 1`)	6	9	12	15
paddingBlock	0	1.5	3	4.5
paddingInline	3	4.5	6	4.5
radius	0	1.5	3	4.5

Tone - K = N / 2 where N is the palette length. For N = 18, K = 9.

Role	Shift	n=0
Background	parent +/- n	0
Text	bg + K	6
Border	bg + K/2	3
Hover	bg + 2K/3	4
Selected / Focus	above +/- K/3	2-4

State shift range: K/3 <= delta <= 2K/3.

ringProgress

import type { PartialElement, StyleObject } from "@domphy/core";
import { toState, type ValueOrState } from "@domphy/core";
import { type ThemeColor, themeColor, themeSpacing } from "@domphy/theme";

/**
 * Circular ring progress indicator rendered via CSS `conic-gradient` and a
 * circular `mask`. Progress starts at 12 o'clock and advances clockwise.
 * Exposes `role="progressbar"` with `aria-valuenow/min/max`. Apply to a `<div>`.
 *
 * @hostTag div
 * @param props.value - Progress percentage 0–100. Accepts a value or reactive state. Defaults to `0`.
 * @param props.color - Theme color for the filled arc. Accepts a value or reactive state. Defaults to `"primary"`.
 * @param props.trackColor - Theme color for the background track. Accepts a value or reactive state. Defaults to `"neutral"`.
 * @param props.size - Diameter in `themeSpacing` units. Defaults to `16` (= `4em`).
 * @param props.thickness - Ring stroke as a fraction of the radius (0–0.5). Defaults to `0.25`.
 * @example { div: null, $: [ringProgress({ value: 65 })] }
 * @example { div: null, $: [ringProgress({ value: loadingState, color: "success", size: 20 })] }
 */
function ringProgress(
  props: {
    value?: ValueOrState<number>;
    color?: ValueOrState<ThemeColor>;
    trackColor?: ValueOrState<ThemeColor>;
    size?: number;
    thickness?: number;
  } = {},
): PartialElement {
  const { size = 16, thickness = 0.25 } = props;
  const value = toState(props.value ?? 0, "value");
  const color = toState(props.color ?? "primary", "color");
  const trackColor = toState(props.trackColor ?? "neutral", "trackColor");

  // Mask cuts the center to create a donut shape.
  // Uses `closest-side` so the gradient circle matches the visible element circle
  // exactly, making `holePercent` directly represent the fraction of outer radius.
  const holePercent = Math.round((1 - thickness) * 100);
  const mask = `radial-gradient(circle closest-side, transparent ${holePercent}%, black ${holePercent}%)`;

  return {
    role: "progressbar",
    ariaValuenow: (l) => String(Math.round(value.get(l))),
    ariaValuemin: "0",
    ariaValuemax: "100",
    _onInsert: (node) => {
      if (node.tagName !== "div") {
        console.warn('"ringProgress" patch must use div tag');
      }
    },
    style: {
      display: "inline-flex",
      alignItems: "center",
      justifyContent: "center",
      width: themeSpacing(size),
      height: themeSpacing(size),
      borderRadius: "50%",
      // Fill arc from 12 o'clock clockwise; `from -90deg` rotates the start point.
      background: (l) =>
        `conic-gradient(from -90deg, ${themeColor(l, "shift-9", color.get(l))} ${value.get(l)}%, ${themeColor(l, "shift-3", trackColor.get(l))} 0%)`,
      WebkitMask: mask,
      mask,
    } as StyleObject,
  };
}

export { ringProgress };

Ring Progress#

Props#

Example#

Ring Progress

Props

Example