Spinner

v1.0.6

Documentation Under Review

Installation

Install the spinner component via your package manager:

npm install @pmi/catalyst-spinner

Usage

Import the spinner component:

import { Spinner } from '@pmi/catalyst-spinner';

Examples

Basic Spinner

A simple loading indicator with the default gradient.

High Contrast Variant

Use the high-contrast variant for better visibility in certain contexts.

Size Variants

Customize the spinner size using Tailwind size utilities.

In Button

Spinner integrated with a button to indicate loading state.

Themes

Component API

Spinner

A loading indicator component with smooth rotation animation.

Variants

Default Variant

Uses a gradient with colors defined by CSS custom properties:

• --components-spinner-default-from - Gradient start color
• --components-spinner-default-to - Gradient end color

High-Contrast Variant

Uses alternative gradient colors for better visibility:

• --components-spinner-high-contrast-from - Gradient start color
• --components-spinner-high-contrast-to - Gradient end color

Size Customization

The spinner's default size is 24px × 24px (size-6). Customize using Tailwind size utilities:

Accessibility

ARIA Attributes

For better accessibility, add ARIA attributes to provide context:

<Spinner role="status" aria-label="Loading" />

With Visually Hidden Text

Provide screen reader text for better context:

<div className="relative">
  <Spinner role="status" />
  <span className="sr-only">Loading content, please wait...</span>
</div>

Best Practices

1. Provide context - Always include text or ARIA labels to describe what's loading
2. Use role="status" - Indicates content area where status messages are displayed
3. Consider aria-live - Use aria-live="polite" for non-critical updates
4. Respect motion preferences - Spinner automatically respects prefers-reduced-motion
5. Don't rely on spinner alone - Combine with descriptive text when possible

Animation

The spinner uses CSS animation with the following characteristics:

• Rotation: Smooth 360° continuous rotation
• Performance: GPU-accelerated for 60fps animation
• Motion preference: Respects prefers-reduced-motion via motion-safe: prefix
• Gradient: Conic gradient creates visual depth effect

CSS Variables

The spinner's gradient colors are controlled by CSS variables defined in your theme configuration. You can customize them:

:root {
  --components-spinner-default-from: /* your color */;
  --components-spinner-default-to: /* your color */;
  --components-spinner-high-contrast-from: /* your color */;
  --components-spinner-high-contrast-to: /* your color */;
}

Integration Patterns

With Buttons

<Button disabled>
  <Spinner className="size-4" />
  <ButtonLabel>Loading</ButtonLabel>
</Button>

With Cards

<Card>
  <div className="flex items-center justify-center p-8">
    <Spinner className="size-8" />
  </div>
</Card>

Loading Overlay

<div className="relative">
  {loading && (
    <div className="absolute inset-0 flex items-center justify-center bg-white/80">
      <Spinner className="size-14" />
    </div>
  )}
  <YourContent />
</div>

Conditional Content

<Spinner loading={isLoading}>
  <DataDisplay data={data} />
</Spinner>

Best Practices

Loading States

1. Inline loading - Use small spinners (size-4) for inline loading indicators
2. Button loading - Use default size (size-6) inside buttons
3. Page loading - Use large spinners (size-14) for full-page loading
4. Optimistic UI - Show content quickly, use spinner only when necessary

Performance

1. CSS animation - Spinners use CSS for optimal performance
2. GPU acceleration - Animation is hardware-accelerated
3. Reduced motion - Automatically respects user preferences
4. Minimal DOM - Simple structure for fast rendering

User Experience

1. Set expectations - Tell users what's loading
2. Show progress - Use with progress indicators when possible
3. Timeout handling - Show error state if loading takes too long
4. Skeleton screens - Consider using instead of spinner for better UX

Related Components

• Button - For loading button states
• Card - For loading card content
• Modal - For loading modal content