Pricing

Spinner handbook

v1.2.3 · @snowui-design-system/components

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Indicate loading with a continuously rotating ring, spokes, or capsules, suitable for buttons and content areas.

When to use it

Use Spinner for ongoing waiting. Use Progress when completion can be measured. Prefer the built-in Spinner in buttons and tables that already provide a loading state.

  • variant selects the animation shape. size takes precedence over the parent size; without a size context it defaults to 16.

  • children are not rendered; place loading text in an external composition. Use Progress when showing completion percentage.

  • The default loading status name follows LocaleProvider; an explicit aria-label takes priority. External loading descriptions remain caller-owned text.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { Spinner, Text, Button } from '@snowui-design-system/components';</script> <div style="display: flex; align-items: center; gap: var(--gap-3);">	<Spinner aria-label="Loading components" />	<Text>Loading components…</Text></div>

API

Keyword Type Default Description
variant SpinnerVariant "circle" Visual variant style
size ResourceSize — Size (12, 16, 20, 24, 28, 32, 40, 48, or 80). When omitted, inherits parent iconSize / size if present, otherwise 16.
speed number 1 Positive animation speed multiplier. Base periods are 1000ms for circle and 800ms for spokes / pills, divided by this multiplier. Non-finite or non-positive values fall back to 1; explicit loopMotion timing takes precedence.
loopMotion LoopMotionConfig — Override the default looping motion configuration, including timing derived from speed. With a preset, Spinner consumes only its timing fields so the root Frame does not rotate again.
children Snippet — Accepted for Frame type compatibility; Spinner renders its own animation, not children. Compose text outside it.

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Layout model

Main layout model: intrinsic atomic layout.

  • The root is an intrinsic box sized by size and variant; it hugs its content when used in another layout.

  • The SVG, mask, spoke, and pill animation layers are private Spinner structure; no Leading / Content / Trailing slots are exposed.

  • Spinner does not arrange a label. Compose “icon + text” in an external Button, Frame, or Text.

  • loopMotion changes only internal loop timing, not root layout.

Keywords

Keyword Type Default Description
class string '' Custom class, for example to change color.

Note on Color & Label

  • Color: Spinner has no color prop. It inherits the current text color (currentColor). Change color with a utility class, for example <Spinner class="snowui-text-blue-500" />.

  • Label: Spinner has no label prop. Compose text in an external layout.

Variants

Variant Description
circle (Default) Ring made with CSS conic-gradient, fading at its head and tail.
spokes Radial spokes with a trailing effect.
pills Thick radial capsules with a trailing effect.

1. Basic usage

The default is a 16px circle.

<Spinner />

2. Variants

<div class="flex gap-4">    <Spinner variant="circle" />    <Spinner variant="spokes" />    <Spinner variant="pills" /></div>

Spinner style overlay

Read the complete LICENSE first; one review covers the same task, version, and scope.

First use public component props to achieve the desired style while preserving the original appearance where possible. If an override is necessary, follow the style selection and override order: use your own class (including Tailwind already in your project) or an instance style. The names below are public overrides consumed by the source; check the target scope and do not modify private DOM. Choose the appropriate SnowUI token category. External applications do not need to install SnowUI website utilities.

Variable Purpose and default reference
--snowui-spinner-size-override Overall size (size px, see the component source code for the default value)

Design Guide · Token · Combination Boundary

Spinner type and status

Required props: no named required props.

Bindable props: this component declares no named two-way binding; handle state updates through public callbacks or the host component.

Inheritance: FrameProps. Consult the public Frame documentation for inherited capabilities.

Shared Frame API · Back to API

The following source type declarations are referenced by public props. Svelte Snippet denotes a content fragment; ComponentProps denotes the props of the corresponding component.

SpinnerVariant

Source: components/src/components/Spinner.svelte

type SpinnerVariant = "circle" | "spokes" | "pills";

ResourceSize

Source: components/src/context.ts

export type ResourceSize = 12 | 16 | 20 | 24 | 28 | 32 | 40 | 48 | 80;

LoopMotionConfig

Source: components/src/logic/frame-types.ts

export interface LoopMotionConfig {    /** Loop preset (enables the full root Frame loop animation) */    preset?: LoopMotionPreset;    /** Loop duration (milliseconds) */    duration?: number;    /** Loop easing function */    easing?: MotionConfig["easing"];    /** Iteration count (default: infinite) */    iterationCount?: number | "infinite" | (string & {});    /** Direction (default: normal) */    direction?:        | "normal"        | "reverse"        | "alternate"        | "alternate-reverse";    /** Playback state (default: running) */    playState?: "running" | "paused";}

LoopMotionPreset

Source: components/src/logic/frame-types.ts

export type LoopMotionPreset = "rotateClockwise";

MotionConfig

Source: components/src/logic/motion-config.ts

export interface MotionConfig {    // === Transform properties ===    /** Scale (1 = 100%) */    scale?: number | [number, number];    /** Horizontal translation (px or a dimension string) */    x?: number | string | [number | string, number | string];    /** Vertical translation (px or a dimension string) */    y?: number | string | [number | string, number | string];    /** Rotation angle (degrees) */    rotate?: number | [number, number];    /** Y-axis rotation (degrees), for front/back flipping */    rotateY?: number | [number, number];    /** Opacity (0–1) */    opacity?: number | [number, number];    /** Blur radius (numeric values are px) */    blur?: number | string | [number | string, number | string];    /** Height (supports "+20px" relative syntax) */    height?: number | string;    /** Width */    width?: number | string;    /** Background color */    backgroundColor?: SnowUIColor | string;    /** Foreground/text/icon color for color transitions */    color?: SnowUIColor | string;     // === Timing parameters ===    /** Delay (milliseconds) */    delay?: number;    /** Duration (milliseconds) */    duration?: number;    /** Easing function */    easing?: EasingFunction;     // === Physics simulation ===    /** Motion type */    type?: 'spring' | 'tween';    /** Spring stiffness (higher is stiffer) */    stiffness?: number;    /** Spring damping (higher stops faster) */    damping?: number;    /** Spring mass */    mass?: number;    /** Spring velocity threshold (lower is stopped) */    velocity?: number;     // === Component reference ===    /** Use a custom component as the motion carrier (for example, FlowText or Spin) */    component?: any;     // === Orchestration control ===    /** Whether to participate in parent orchestration */    orchestrate?: boolean;}

SnowUIColor

Source: components/src/lib/color.ts

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

EasingFunction

Source: components/src/logic/motion-config.ts

export type EasingFunction =    | 'linear'    | 'easeIn' | 'easeOut' | 'easeInOut'    | 'cubicIn' | 'cubicOut' | 'cubicInOut'    | 'quadIn' | 'quadOut' | 'quadInOut'    | 'quartIn' | 'quartOut' | 'quartInOut'    | 'quintIn' | 'quintOut' | 'quintInOut'    | 'sineIn' | 'sineOut' | 'sineInOut'    | 'expoIn' | 'expoOut' | 'expoInOut'    | 'circIn' | 'circOut' | 'circInOut'    | 'backIn' | 'backOut' | 'backInOut'    | 'elasticIn' | 'elasticOut' | 'elasticInOut'    | 'bounceIn' | 'bounceOut' | 'bounceInOut'    | (string & {});