Kappa / Progress Circle

72%Simulation

<script setup>
import { ProgressCircle } from "@dicehub/kappa/components/progress-circle";
</script>

<template>
  <ProgressCircle.Root :default-value="72">
    <ProgressCircle.Circle aria-label="Simulation progress">
      <ProgressCircle.CircleTrack />
      <ProgressCircle.CircleRange />
    </ProgressCircle.Circle>
    <ProgressCircle.ValueText />
    <ProgressCircle.Label>Simulation</ProgressCircle.Label>
  </ProgressCircle.Root>
</template>

Installation

Progress Circle is part of the main Kappa package. It uses Ark UI's circular Progress anatomy.

Barrel

import {
  ProgressCircle,
  ProgressCircleGraphic,
  ProgressCircleRange,
  ProgressCircleRoot,
  ProgressCircleTrack,
  ProgressCircleValueText,
} from "@dicehub/kappa";

Granular

import {
  ProgressCircle,
  ProgressCircleGraphic,
  ProgressCircleRange,
  ProgressCircleRoot,
  ProgressCircleTrack,
  ProgressCircleValueText,
} from "@dicehub/kappa/components/progress-circle";

Usage

Use Progress Circle when horizontal space is limited or when progress belongs to one compact object. Use linear Progress when the label or exact status needs more space.

72%Simulation

<script setup>
import { ProgressCircle } from "@dicehub/kappa/components/progress-circle";
</script>

<template>
  <ProgressCircle.Root :default-value="72">
    <ProgressCircle.Circle aria-label="Simulation progress">
      <ProgressCircle.CircleTrack />
      <ProgressCircle.CircleRange />
    </ProgressCircle.Circle>
    <ProgressCircle.ValueText />
    <ProgressCircle.Label>Simulation</ProgressCircle.Label>
  </ProgressCircle.Root>
</template>

Composition

Typical part hierarchy

ProgressCircle.Root
├── ProgressCircle.Label
├── ProgressCircle.ValueText
├── ProgressCircle.Circle
│   ├── ProgressCircle.CircleTrack
│   └── ProgressCircle.CircleRange
├── ProgressCircle.View (optional)
└── ProgressCircle.Context (optional)

Progress Circle shares Ark UI's Progress state machine with linear Progress. Kappa gives the circular anatomy a separate import path, namespace, data slots, and visual contract.

Circle is the SVG progressbar and owns the accessible name.
CircleTrack shows the complete range.
CircleRange shows the current arc or indeterminate sweep.
ValueText is centered over the SVG by default.

Examples

Size and Thickness

Set the public CSS variables on the root to fit compact status areas or larger summaries.

28%Small

62%Default

84%Large

<script setup>
import { ProgressCircle } from "@dicehub/kappa/components/progress-circle";

const items = [
  { label: "Small", size: "3rem", thickness: "0.25rem", value: 28 },
  { label: "Default", size: "4.5rem", thickness: "0.375rem", value: 62 },
  { label: "Large", size: "6rem", thickness: "0.5rem", value: 84 },
];
</script>

<template>
  <ProgressCircle.Root
    v-for="item in items"
    :key="item.label"
    :default-value="item.value"
    :style="{
      '--kappa-progress-circle-size': item.size,
      '--kappa-progress-circle-thickness': item.thickness,
    }"
  >
    <ProgressCircle.Circle :aria-label="item.label + ' progress'">
      <ProgressCircle.CircleTrack />
      <ProgressCircle.CircleRange />
    </ProgressCircle.Circle>
    <ProgressCircle.ValueText />
    <ProgressCircle.Label>{{ item.label }}</ProgressCircle.Label>
  </ProgressCircle.Root>
</template>

Indeterminate

Set the value to null when completion cannot be estimated.

•••Preparing results

<script setup>
import { ProgressCircle } from "@dicehub/kappa/components/progress-circle";
</script>

<template>
  <ProgressCircle.Root :model-value="null">
    <ProgressCircle.Circle aria-label="Preparing results">
      <ProgressCircle.CircleTrack />
      <ProgressCircle.CircleRange />
    </ProgressCircle.Circle>
    <ProgressCircle.ValueText>•••</ProgressCircle.ValueText>
    <ProgressCircle.Label>Preparing results</ProgressCircle.Label>
  </ProgressCircle.Root>
</template>

Controlled

Use v-model when application state owns the current progress value.

42%Export

Set progress

<script setup>
import { ProgressCircle } from "@dicehub/kappa/components/progress-circle";
import { ref } from "vue";

const value = ref(42);
</script>

<template>
  <ProgressCircle.Root v-model="value">
    <ProgressCircle.Circle aria-label="Export progress">
      <ProgressCircle.CircleTrack />
      <ProgressCircle.CircleRange />
    </ProgressCircle.Circle>
    <ProgressCircle.ValueText />
    <ProgressCircle.Label>Export</ProgressCircle.Label>
  </ProgressCircle.Root>

  <label>
    Set progress
    <input v-model.number="value" type="range" min="0" max="100" />
  </label>
</template>

Accessibility

Circle exposes role=progressbar, its range, state, and current value.
Give the SVG progressbar an accessible name that identifies the process.
Do not rely on the arc alone. Keep a visible label or nearby status description.
A null value removes aria-valuenow and signals an indeterminate process.
Reduced-motion preferences stop both circular animations and the value transition.

API Reference

ProgressCircle.Root

Prop	Type	Default	Description
`modelValue / defaultValue`	`number \| null`	`50`	Controlled value or initial value. Null selects the indeterminate state.
`min / max`	`number`	`0 / 100`	Numeric range used for arc geometry and value text.
`formatOptions`	`Intl.NumberFormatOptions`	`percent`	Formats the default ValueText output.
`locale`	`string`	`"en-US"`	Locale used to format the value.
`translations`	`IntlTranslations`	`Ark defaults`	Customizes the assistive value description.
`id / ids`	`string / partial ID map`	`generated`	Overrides the machine and part identifiers.
`asChild`	`boolean`	`false`	Merges root behavior into the direct child.

Parts

Part	Element	Description
`ProgressCircle.Label`	`label`	Visible progress label.
`ProgressCircle.ValueText`	`span`	Formatted value centered over the circle.
`ProgressCircle.Circle`	`svg`	Progressbar element and circular coordinate space.
`ProgressCircle.CircleTrack`	`circle`	Complete circular range.
`ProgressCircle.CircleRange`	`circle`	Determinate arc or indeterminate sweep.
`ProgressCircle.View`	`div`	Content shown for loading, complete, or indeterminate state.
`ProgressCircle.Context`	`renderless`	Exposes the Ark progress context to a slot.

CSS Variables

Variable	Default	Description
`--kappa-progress-circle-size`	`4.5rem`	SVG width and height.
`--kappa-progress-circle-thickness`	`0.375rem`	Track and range stroke width.
`--kappa-progress-circle-range-color`	`accent solid`	Range stroke color.

Events

Event	Payload	Description
`update:modelValue`	`number \| null`	Updates v-model when the Ark machine value changes.
`valueChange`	`ProgressValueChangeDetails`	Reports each value change.

Exports

Export	Description
`ProgressCircle`	Styled compound component with all circular parts.
`ProgressCircleRoot / ProgressCircleRootProvider`	Direct root and external-machine provider components.
`ProgressCircleGraphic / ProgressCircleTrack / ProgressCircleRange`	Granular styled SVG parts.
`ProgressCircleLabel / ProgressCircleValueText`	Visible label and formatted value parts.
`ProgressCircleView / ProgressCircleContext`	State view and renderless context parts.
`useProgress / useProgressContext`	Ark UI composition functions.
`ProgressCircleProps / ProgressCircleSlots`	Public TypeScript contracts.