FEEDBACKBETA

ProgressSpinner

Accessible indeterminate progress with semantic color, normalized motion, localized naming and complete visual ownership.

ARIA progressbarReduced-motion safeHeadless ready

GET STARTED

Import

Import the standalone component from its granular entry point.

import {
  NeuralProgressSpinner,
  type NeuralProgressSpinnerClasses,
} from '@neural-ng/core/progress-spinner';

@Component({ imports: [NeuralProgressSpinner] })

Basic indeterminate progress

Use a spinner when work is active but its completion percentage is unknown.

Solid, multicolor, dynamic and dual

Solid keeps one semantic severity. Multicolor cycles through five semantic colors, while dynamicStroke grows and contracts the visible arc. Dual adds a counter-rotating inner ring and reverse flips both directions. Dual colors stay synchronized unless syncDualColor is disabled.

Semantic severities

Every severity follows the shared NeuralNg color contract, including runtime primary changes.

Sizes

Human-readable size values keep the public API framework-neutral and AI-friendly.

Labels and accessible naming

Visible text can describe the operation while ariaValueText supplies more specific assistive status.

Synchronizing workspace

Stroke and speed

Stroke width and rotation duration are normalized to safe ranges before rendering.

Unstyled and typed slots

Progress semantics and structural hooks remain while consumer classes own every visible decision.

Agent is reasoning

Usage boundaries

Use ProgressSpinner for unknown-duration work, ProgressBar for measurable completion, and LoadingOverlay only when interaction must be blocked.

ACCESSIBILITY

Unknown progress, clearly announced

The visible arc is decorative; the containing progressbar communicates the actual task state.

Indeterminate semantics

The root exposes role="progressbar" without invented aria-valuenow, min or max attributes.

Accessible names

ariaLabelledBy takes precedence over ariaLabel, then the explicit label, then the active locale's common loading message.

Value descriptions

ariaValueText can announce domain state such as �Waiting for approval� without forcing that copy into the visual layout.

Reduced motion

Under prefers-reduced-motion: reduce, rotation stops and a static arc continues to communicate activity visually.

Localization

An unlabeled spinner resolves its accessible name from NeuralLocaleService.messages().common.loading and updates with the active locale.

SSR and hydration

Signal normalization and locale resolution avoid browser globals, keeping server and client markup deterministic.

PUBLIC CONTRACT

ProgressSpinner API

A small Signal input surface for semantic, indeterminate loading feedback.

Inputs

Input	Type	Default	Purpose
size	'small' \| 'medium' \| 'large'	'medium'	Spinner diameter preset.
variant	'solid' \| 'multicolor'	'solid'	Single semantic color or an animated five-color cycle.
severity	NeuralProgressSpinnerSeverity	'info'	Semantic indicator color.
dynamicStroke	boolean	false	Grows and contracts the visible arc while it rotates.
dual	boolean	false	Adds a counter-rotating inner track and indicator.
reverse	boolean	false	Reverses the primary direction while dual arcs stay opposed.
syncDualColor	boolean	true	Keeps both dual arcs on the same multicolor cycle.
strokeWidth	number	4	SVG stroke width, clamped from 1 through 12.
speed	number	900	Rotation duration in milliseconds, clamped from 200 through 10000.
label	string \| null	null	Optional visible loading label.
showLabel	boolean	true	Controls visible label rendering while preserving its accessible fallback.
ariaLabel	string \| null	null	Direct accessible name.
ariaLabelledBy	string \| null	null	ID reference that takes precedence over ariaLabel.
ariaValueText	string \| null	null	Optional human-readable task state.
unstyled	boolean	false	Removes NeuralNg visual classes.
spinnerClass	string	''	Additive root classes.
classes	NeuralProgressSpinnerClasses	{}	Typed outer, inner and label class slots.

Typed class slots

root

Semantic progressbar and label layout.

svg

Decorative SVG viewport.

track

Static circular track.

indicator

Animated indeterminate arc.

inner

Scaled inner-ring group rendered by dual mode.

innerTrack

Static inner circular track.

innerIndicator

Counter-rotating inner arc.

label

Optional visible loading text.

Public types

NeuralProgressSpinnerSize

'small' | 'medium' | 'large'

NeuralProgressSpinnerVariant

'solid' | 'multicolor'

NeuralProgressSpinnerSeverity

NeuralProgressSpinnerClasses

{ root?, svg?, track?, indicator?, inner?, innerTrack?, innerIndicator?, label? }

Legacy alias

ProgressSpinnerComponent remains compatible. New code should import NeuralProgressSpinner.

DESIGN TOKENS

ProgressSpinner tokens

Every custom property below maps to a real spinner implementation detail.

Layout and sizes

--neural-progress-spinner-small-size

Small width and height.

--neural-progress-spinner-medium-size

Medium width and height.

--neural-progress-spinner-large-size

Large width and height.

--neural-progress-spinner-gap

Spacing between component items.

--neural-progress-spinner-font-family

Component font family.

--neural-progress-spinner-dual-scale

Scale of the inner ring relative to the outer ring.

--neural-progress-spinner-dual-track-opacity

Opacity of the inner circular track in dual mode.

--neural-progress-spinner-dual-indicator-opacity

Opacity of the animated inner arc in dual mode.

Surface

--neural-progress-spinner-track-color

Track foreground color.

--neural-progress-spinner-indicator-color

Indicator foreground color.

--neural-progress-spinner-filter

Component CSS filter effect.

Color and severity

--neural-progress-spinner-primary-color

Primary severity foreground color.

--neural-progress-spinner-secondary-color

Secondary severity foreground color.

--neural-progress-spinner-neutral-color

Neutral severity foreground color.

--neural-progress-spinner-info-color

Info severity foreground color.

--neural-progress-spinner-success-color

Success severity foreground color.

--neural-progress-spinner-warning-color

Warning severity foreground color.

--neural-progress-spinner-error-color

Error severity foreground color.

--neural-progress-spinner-color-1

First color in the multicolor spinner cycle.

--neural-progress-spinner-color-2

Second color in the multicolor spinner cycle.

--neural-progress-spinner-color-3

Third color in the multicolor spinner cycle.

--neural-progress-spinner-color-4

Fourth color in the multicolor spinner cycle.

--neural-progress-spinner-color-5

Fifth color in the multicolor spinner cycle.

Label

--neural-progress-spinner-label-color

Label foreground color.

--neural-progress-spinner-label-font-size

Label font size.

--neural-progress-spinner-label-font-weight

Label font weight.

--neural-progress-spinner-label-line-height

Label line height.

Motion

--neural-progress-spinner-duration

Component animation duration.

--neural-progress-spinner-dasharray

Stroke dash pattern that controls the visible spinner arc length.

--neural-progress-spinner-easing

Component animation easing curve.

--neural-progress-spinner-linecap

Stroke line-cap style applied to spinner arcs.

--neural-progress-spinner-color-duration

Duration of one complete multicolor cycle.

--neural-progress-spinner-dynamic-stroke-duration

Duration of one arc growth and contraction cycle.