ProgressCircular
SVG-based circular progress indicator. Supports determinate, indeterminate and custom size modes.
Preview
Rendering the live preview…
indeterminateRendering the live preview…
25%Rendering the live preview…
50%Rendering the live preview…
75%Rendering the live preview…
100%Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-progress-circular> — 4 internal parts: root container ①, background SVG ring ②, foreground SVG arc ③, and content slot for inner label ④.- 1.origam-progress--circular
- Root element.
display: inline-flex; position: relative. Size driven by size prop via useSize →origam-progress--size-{size}modifier. - 2.origam-progress__underlay
- Background SVG circle (
<circle>). Color from bgColor prop. Opacity 0.5 by default. z-index: 1. - 3.origam-progress__overlay
- Foreground SVG arc. stroke-dashoffset driven by normalised value. In indeterminate mode: animated via CSS keyframes. z-index: 2.
- 4.origam-progress__content
- Center content area. Rendered only when the #default slot is filled.
display: flex; align-items: center; justify-content: center.
API
Props
All props accepted by this component, with their type, default value and description.
- rotatestring | number0
- Rotation offset applied to the SVG. The start point defaults to the top (−90 deg applied internally).
- indeterminatebooleanfalse
- Activates the continuous spin animation (unknown duration). Overrides modelValue display.
- modelValuestring | number0
- Current progress value between 0 and max. Ignored in indeterminate mode.
- thicknessstring | number4
- Stroke width of the SVG circles. Accepts a number (px) or CSS length.
- activebooleantrue
- When false, the component is hidden (visibility: hidden).
- absolutebooleanfalse
- Positions the component absolutely within its container.
- maxnumber | string100
- Maximum value used to normalise modelValue into a 0-100 percentage.
- stripedbooleanfalse
- Adds a stripe pattern to the progress arc.
- labelstring'Loading'
- Accessible label (aria-label) for the progress indicator. Pass a localised string.
- tagstring'div'
- Root HTML element.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- color
- Foreground arc color. Accepts intent tokens (primary, success…) or a CSS color.
- bgColor
- Background ring color. Defaults to --origam-progress-circular__underlay---color (color.surface.disabled at 50% opacity).
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- Controls the component dimensions. Named sizes: x-small (16), small (24), default (32), large (48), x-large (64). A number sets an explicit pixel size.
API
Slots
Content slots exposed by this component.
- #default
- Content rendered inside the circular progress (e.g. a percentage label). Slot prop value is the normalised 0-100 value.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to child components.
- Ref<string>
- Reactive CSS string generated by useStyle.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet into the document.
- () => void
- Removes the injected style sheet.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Color of the background ring. Resolves to neutral.200 (light) / neutral.800 (dark).
- Opacity of the background ring.
- Foreground arc color. Overridden at runtime by the color prop via useTextColor.
- Duration of the stroke-dashoffset transition in determinate mode.
- Easing function for the stroke transition.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Notes
- The component applies role="progressbar" via the progress composable. aria-valuenow, aria-valuemin (0) and aria-valuemax are bound automatically.
- Pass the label prop with a localised string to set aria-label. Defaults to "Loading".
- Under prefers-reduced-motion: reduce, the CSS spin and dash animations are disabled.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- dimension32px
- Default (medium) size: 32 × 32 px.
- colorvar(--origam-color__surface---disabled)
- Background ring color — muted track.
- numbervar(--origam-opacity---50)
- Background ring opacity.
- colorvar(--origam-color__action--primary---bg)
- Default foreground arc color (overridden by color prop at runtime).
- durationvar(--origam-motion__duration---medium)
- Arc transition duration in determinate mode.
- duration1400ms
- Duration of the indeterminate spin/dash SVG animations.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Determinate
Indeterminate
Sizes
Ecosystem
Family
Components from the same folder that share conventions and often compose together.