Components

Spinner

A loading spinner component with color, size, and optional overlay — built as a multi-part recipe system with SVG-based animation.

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:

src/components/spinner.styleframe.ts
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:

src/components/Spinner.tsx
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

ColorTokenUse Case
primary@color.primary, @color.primary-400 in dark modeDefault loading state, primary actions
light@color.gray-700Loading on light surfaces, in both themes
dark@color.whiteLoading on dark surfaces, like the overlay's backdrop, in both themes
neutralAdaptive (light ↔ dark)Default adaptive color, adjusts to the current color scheme
Pro tip: Use 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.

SizeSpinner DimensionsFont Size
auto100% × 100%Inherits base
sm@2 × @2@font-size.xs
md@3 × @3@font-size.sm
lg@4 × @4@font-size.md
inherit1em × 1emInherits 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.

src/components/SpinnerOverlay.vue
<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 primary and neutral, light surfaces for light, and dark surfaces, like the overlay's backdrop, for dark. 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 why primary uses the dark modifier to switch to @color.primary-400 in dark mode. The light and dark colors stay @color.gray-700 and @color.white in both themes, so use neutral when the spinner sits on the page and must adapt to the theme.
  • Size: The inherit size is 1em wide and tall and sits 0.125em below 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-reduce modifier 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

src/components/spinner.styleframe.ts
const spinner = useSpinnerRecipe(s, {
    defaultVariants: { color: 'neutral', size: 'lg' },
});

Filtering Variants

src/components/spinner.styleframe.ts
const spinner = useSpinnerRecipe(s, {
    filter: {
        color: ['primary', 'neutral'],
    },
});
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

API Reference

useSpinnerRecipe(s, options?)

Creates the spinner container recipe with color and size variants.

Parameters:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles
options.variantsVariantsCustom variant definitions
options.defaultVariantsRecord<keyof Variants, string>Default variant values
options.compoundVariantsCompoundVariant[]Custom compound variant definitions
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
colorprimary, light, dark, neutralprimary
sizeauto, sm, md, lg, inheritmd

useSpinnerCircleRecipe(s, options?)

Creates the SVG spinner recipe with size variants and animation keyframes.

Variants:

VariantOptionsDefault
sizeauto, sm, md, lg, inheritmd

useSpinnerOverlayRecipe(s, options?)

Creates the overlay backdrop recipe. No variants — provides a fixed full-screen backdrop.

Learn more about recipes ->

Best Practices

  • Say what's loading in a status message, and hide the <svg> with aria-hidden="true".
  • Provide a label for longer loading operations so users know what's happening.
  • Choose the right color: Use primary for brand-colored spinners, neutral for general use, and dark on dark surfaces like the overlay.
  • Filter what you don't need: Pass a filter option to reduce generated CSS.
  • Use the overlay sparingly: Full-page overlays block interaction — prefer inline spinners when possible.

FAQ