Spinner
Overview
The Spinner is a visual indicator used to communicate that an action is in progress. The useSpinnerRecipe() composable creates a fully configured recipe with color and size options, while useSpinnerCircleRecipe() handles the SVG spinner animation and useSpinnerOverlayRecipe() provides an optional backdrop overlay.
The Spinner recipe integrates directly with the default design tokens preset and generates type-safe utility classes at build time with zero runtime CSS.
Why use the Spinner recipe?
The Spinner recipe helps you:
- Ship faster with sensible defaults: Get 4 colors and 5 sizes out of the box with a single composable call.
- Maintain consistency: The SVG-based spinner animation is consistent across all color and size combinations.
- Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
- Stay type-safe: Full TypeScript support means your editor catches invalid color or size values at compile time.
- Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.
Usage
Register the recipes
Add the Spinner recipes to a local Styleframe instance. The global styleframe.config.ts provides design tokens and utilities, while the component-level file registers the recipes themselves:
import { styleframe } from 'virtual:styleframe';
import { useSpinnerRecipe, useSpinnerCircleRecipe, useSpinnerOverlayRecipe } from '@styleframe/theme';
const s = styleframe();
const spinner = useSpinnerRecipe(s);
const spinnerCircle = useSpinnerCircleRecipe(s);
const spinnerOverlay = useSpinnerOverlayRecipe(s);
export default s;
Build the component
Import the spinner and spinnerCircle runtime functions from the virtual module and pass variant props to compute class names:
import { spinner, spinnerCircle, type SpinnerProps } from "virtual:styleframe";
interface SpinnerComponentProps extends SpinnerProps {
label?: string;
children?: React.ReactNode;
}
export function Spinner({
color = "primary",
size = "md",
label,
children,
}: SpinnerComponentProps) {
const containerClasses = spinner({ color, size });
const circleClasses = spinnerCircle({ size });
return (
<div className={containerClasses} role="status">
<svg className={circleClasses} viewBox="0 0 50 50" aria-hidden="true">
<circle cx="25" cy="25" r="20" />
</svg>
{label && <span>{label}</span>}
{children}
</div>
);
}
See it in action
Colors
The Spinner supports 4 color options. The color variant sets the CSS color property on the container, which cascades to the SVG spinner via currentColor.
Color Reference
| Color | Token | Use Case |
|---|---|---|
primary | @color.primary, @color.primary-400 in dark mode | Default loading state, primary actions |
light | @color.gray-700 | Loading on light surfaces, in both themes |
dark | @color.white | Loading on dark surfaces, like the overlay's backdrop, in both themes |
neutral | Adaptive (light ↔ dark) | Default adaptive color, adjusts to the current color scheme |
neutral for general-purpose loading states that need to adapt to both light and dark mode automatically.Sizes
The Spinner comes in fixed sizes that control both the spinner dimensions and the label text size, plus auto, which fills its container, and inherit, which matches the text around it.
| Size | Spinner Dimensions | Font Size |
|---|---|---|
auto | 100% × 100% | Inherits base |
sm | @2 × @2 | @font-size.xs |
md | @3 × @3 | @font-size.sm |
lg | @4 × @4 | @font-size.md |
inherit | 1em × 1em | Inherits the surrounding text |
Use inherit when the spinner sits in a line of text, like a status message or a heading, so it grows with the text at any zoom level:
Label
You can display optional text below the spinner using the label prop.
Overlay
Use useSpinnerOverlayRecipe() to create a fixed overlay backdrop for full-page or container-level loading states. The backdrop is black at 75% opacity, dark enough for a dark spinner and its label on any page.
<script setup lang="ts">
import { spinnerOverlay } from "virtual:styleframe";
</script>
<template>
<div :class="spinnerOverlay({})">
<Spinner color="dark" size="lg" label="Loading..." />
</div>
</template>
Accessibility
The Spinner recipes follow the stylesheet rules of the Open Components Spinner standard. Here's what they do for you:
- Color: The circle is drawn in
currentColor, so it follows the color the container sets, the color scheme and forced colors mode, where it takes the system's text color without any styles of its own. - Contrast: The spinner has no background of its own, so each color is chosen for what it sits on: the page for
primaryandneutral, light surfaces forlight, and dark surfaces, like the overlay's backdrop, fordark. There, the circle has a contrast of at least 3:1 (WCAG 1.4.11) and the label, which takes the spinner's color, at least 4.5:1 (WCAG 1.4.3), in the light and dark themes. That's whyprimaryuses thedarkmodifier to switch to@color.primary-400in dark mode. Thelightanddarkcolors stay@color.gray-700and@color.whitein both themes, so useneutralwhen the spinner sits on the page and must adapt to the theme. - Size: The
inheritsize is1emwide and tall and sits0.125embelow the baseline, so it matches the text around it, centres on it and grows with it at 200% text size (WCAG 1.4.4). - Stable layout: The spinner keeps a fixed size while it turns, since it turns with
transform, which takes up no room, and it doesn't shrink in a flex row (flex-shrink: 0). The label sits over the circle, so it doesn't move anything either. - Reduced motion: When someone prefers reduced motion, the
motion-reducemodifier swaps the turn for a pulse, which fades the spinner to 40% and back every 1.6 seconds, and the arc stops growing and shrinking (WCAG 2.3.3). The pulse keeps going even with the sanitize preset, which stops every other animation, because a still circle looks as if the page has frozen. - Focus: The spinner can't be focused, so it draws no focus ring. The controls around it show theirs in
color.focus, as they do everywhere else.
The recipes handle styling only. The behaviour below is up to your component:
- Hide the spinner from assistive technologies: Put
aria-hidden="true"on the<svg>, so screen readers don't read it out as an image. - Say what's loading: Put the text in a status message (
role="status") that's in the page before the wait starts, so screen readers announce it. - Take it out when the wait ends, and say how it went in the same status message.
Customization
Overriding Defaults
const spinner = useSpinnerRecipe(s, {
defaultVariants: { color: 'neutral', size: 'lg' },
});
Filtering Variants
const spinner = useSpinnerRecipe(s, {
filter: {
color: ['primary', 'neutral'],
},
});
API Reference
useSpinnerRecipe(s, options?)
Creates the spinner container recipe with color and size variants.
Parameters:
| Parameter | Type | Description |
|---|---|---|
s | Styleframe | The Styleframe instance |
options | DeepPartial<RecipeConfig> | Optional overrides for the recipe configuration |
options.base | VariantDeclarationsBlock | Custom base styles |
options.variants | Variants | Custom variant definitions |
options.defaultVariants | Record<keyof Variants, string> | Default variant values |
options.compoundVariants | CompoundVariant[] | Custom compound variant definitions |
options.filter | Record<string, string[]> | Limit which variant values are generated |
Variants:
| Variant | Options | Default |
|---|---|---|
color | primary, light, dark, neutral | primary |
size | auto, sm, md, lg, inherit | md |
useSpinnerCircleRecipe(s, options?)
Creates the SVG spinner recipe with size variants and animation keyframes.
Variants:
| Variant | Options | Default |
|---|---|---|
size | auto, sm, md, lg, inherit | md |
useSpinnerOverlayRecipe(s, options?)
Creates the overlay backdrop recipe. No variants — provides a fixed full-screen backdrop.
Best Practices
- Say what's loading in a status message, and hide the
<svg>witharia-hidden="true". - Provide a label for longer loading operations so users know what's happening.
- Choose the right color: Use
primaryfor brand-colored spinners,neutralfor general use, anddarkon dark surfaces like the overlay. - Filter what you don't need: Pass a
filteroption to reduce generated CSS. - Use the overlay sparingly: Full-page overlays block interaction — prefer inline spinners when possible.
FAQ
spinner-rotate for continuous rotation and spinner-dash for the stroke dash effect that creates the "chasing" appearance. With reduced motion, a third one, spinner-pulse, takes their place. All three are registered automatically when you call useSpinnerCircleRecipe().useSpinnerRecipe sets the CSS color property via compound variants. The SVG circle's stroke is set to currentColor via a selector in the spinner circle recipe's setup function. This means the spinner color automatically inherits from the container — no extra wiring needed.filter option, compound variants that reference filtered-out values are automatically removed. Default variants are also adjusted if they reference a removed value.Yes! Override the overlay's position to absolute and ensure the parent container has position: relative:
const spinnerOverlay = useSpinnerOverlayRecipe(s, {
base: { position: 'absolute' },
});
Skeleton
A loading placeholder component that displays a pulsing gray block to indicate content is being loaded. Supports multiple sizes and a rounded option through the recipe system.
Toast
A transient, floating feedback component for notifications and status messages. Supports multiple colors, visual styles, sizes, and orientations through the recipe system.