HySpinner

Usage examples on this page are written for Lit / plain HTML (<hy-spinner>). The same component ships as HySpinner in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A visual loading indicator that shows an indeterminate spinning animation.

The spinner component displays an animated circular indicator to communicate that content is loading or a process is in progress. It's purely indeterminate— for showing progress percentages, use the Progress component instead.

Key Features:

• Three size variants (small, medium, large)
• Customizable colors via CSS custom properties
• Accessible with proper ARIA attributes
• CSS-based animation for performance
• SSR compatible

Accessibility Features:

• Uses role="status" for screen reader announcements
• Requires label prop for accessible name via aria-label
• High contrast and forced colors mode support
• Respects prefers-reduced-motion (stops animation)

When to Use:

• Loading content (< 10 seconds expected)
• Submitting forms
• Processing actions
• Fetching data

When NOT to Use:

• For determinate progress (use Progress component)
• For very long operations (use Progress with percentage)
• For page-level loading (consider skeleton screens)

Examples

Basic usage

<hy-spinner label="Loading"></hy-spinner>

Different sizes

<hy-spinner size="small" label="Loading"></hy-spinner>
<hy-spinner size="medium" label="Loading"></hy-spinner>
<hy-spinner size="large" label="Loading"></hy-spinner>

In a button

<hy-button disabled>
  <hy-spinner size="small" label="Saving"></hy-spinner>
  Saving...
</hy-button>

API

Properties

Property	Attribute	Type	Default	Description
size	size	'small' | 'medium' | 'large'	'medium'	The size of the spinner.
label	label	string	'Loading'	Accessible label describing what is loading.

CSS Parts

Part	Description
base	The SVG element containing the spinner
track	The background track circle
indicator	The animated spinning indicator

CSS Custom Properties

Property	Description
--hy-spinner-stroke-sm	Stroke width for small size
--hy-spinner-stroke-md	Stroke width for medium size
--hy-spinner-stroke-lg	Stroke width for large size
--hy-spinner-spin-duration	Rotation duration of the spinner
--hy-spinner-spin-easing	Rotation easing of the spinner