React Spinny

A lightweight, typed React spinner with three variants and no runtime dependencies beyond React.

Installation

pnpm add react-spinny

React 18 or 19 is required.

Usage

import { Spinner } from 'react-spinny'

export function LoadingMessage() {
  return (
    <Spinner
      role="status"
      aria-label="Loading"
      variant="rounded"
      foreground="#3b82f6"
    />
  )
}

The component is semantically neutral. Add role="status" and an accessible name when it communicates loading, or use aria-hidden when it is decorative.

<Spinner aria-hidden />

Props

| Prop | Type | Default | Description | | ------------- | ------------------------------------- | ---------------------- | ---------------------------------------------------- | | variant | 'default' \| 'rounded' \| 'quarter' | 'default' | Visual style | | foreground | string | 'oklch(0 0 0)' | Foreground color | | background | string | 'oklch(0 0 0 / 0.5)' | Track color for quarter | | size | number | 40 | Size in pixels | | strokeWidth | number | 6 | Thickness in pixels; clamped from 0 to half the size | | duration | number | 800 | Rotation duration in milliseconds | | ...props | HTMLAttributes<HTMLDivElement> | — | Standard div attributes |

Consumer styles override individual generated properties without removing the rest of the spinner:

<Spinner style={{ width: 64, margin: '20px auto' }} />

Hook

import { useSpinner } from 'react-spinny'

export function CustomSpinner() {
  const { style } = useSpinner({
    variant: 'quarter',
    foreground: '#f59e0b',
    background: '#e5e7eb',
    size: 48,
    strokeWidth: 6,
    duration: 1000
  })

  return (
    <div
      role="status"
      aria-label="Loading"
      style={style}
    />
  )
}

Types

import type { SpinnerOptions, SpinnerProps, SpinnerVariant } from 'react-spinny'

Development

Node.js 24 and pnpm 11 are required.

pnpm install
pnpm quality
pnpm test:coverage
pnpm build:lib
pnpm build:storybook
pnpm validate:package

Release

Changesets creates the version pull request but never publishes automatically. After merging that pull request, use a clean master checkout with npm 2FA configured:

pnpm release
git push --follow-tags

License

MIT © Benja Osuna