react-spinners

react-spinners is a TypeScript library of 23 self-contained loading spinner components for React, ported from the Halogen CSS spinner set. Each loader (ClipLoader, PulseLoader, BarLoader, and 20 others) is a small functional component that renders pure CSS/keyframe animations with no external styling dependencies, images, or SVGs.

Every loader shares a common prop contract: a loading boolean that toggles rendering, a color, an optional cssOverride object for inline style overrides, speedMultiplier to adjust animation speed, and size-related props (size, height/width, radius, margin) that accept numbers or valid CSS unit strings. The package ships dual CJS/ESM builds, full TypeScript types, and zero runtime dependencies, making it a drop-in choice for showing loading state in any React 16-19 application.

What You Get

• 23 distinct spinner components (ClipLoader, BarLoader, BounceLoader, PulseLoader, RingLoader, and more) covering common loading-indicator shapes
• A consistent prop API across every loader: loading, color, cssOverride, speedMultiplier, plus shape-specific sizing props
• Full TypeScript typings and dual CommonJS/ESM builds via separate tsconfig.cjs.json/tsconfig.esm.json compiles
• Zero runtime dependencies — animations are generated as CSS keyframes injected at runtime via a shared createAnimation helper
• Automatic CSS-unit validation and coercion for size/height/width/radius/margin props, with a console warning on invalid units
• “use client” directives on every component for compatibility with React Server Component frameworks like Next.js App Router

Common Use Cases

• Showing a loading indicator while an async data fetch or API call resolves
• Providing visual feedback during form submission or button click actions
• Full-page or full-section loading states in dashboards and SPAs
• Skeleton/placeholder loading UI for content that streams in after route navigation
• Overriding loader colors and sizes to match a design system via cssOverride

Under The Hood

Architecture The library is a flat collection of 23 independent functional components in src/, one file per loader (e.g. ClipLoader.tsx, BarLoader.tsx), each re-exported by name from a single src/index.ts barrel file. There is no class hierarchy, context, or internal state — every loader is a pure function of its props that computes an inline style object and returns a span (or a small nested set of spans for multi-element loaders). Shared cross-cutting concerns live in src/helpers/: animation.ts exposes a createAnimation function that injects a @keyframes rule into document.head and returns its generated name (guarded for non-DOM/server environments), unitConverter.ts normalizes numeric or string size props into valid CSS length values, and props.ts defines a small set of shared TypeScript interfaces (LoaderSizeProps, LoaderHeightWidthProps, LoaderSizeMarginProps, LoaderHeightWidthRadiusProps) that every loader extends. Because every one of the 23 components depends on the same two helpers, a change to unitConverter or createAnimation propagates uniformly across the entire component set — a simple, low-risk architecture for a component library of this scope.

Tech Stack Written in TypeScript (the large majority of the codebase) with React as a peer dependency supporting versions 16 through 19, and “use client” directives on each component for compatibility with React Server Component frameworks such as Next.js App Router. The build pipeline compiles the same TypeScript source twice via tsc, once to CommonJS (tsconfig.cjs.json) and once to ES modules (tsconfig.esm.json), producing a dual-format, tree-shakeable package with bundled type declarations. A companion demo/documentation site is built with Vite and Storybook (with a Ruby script generating stories), and the project uses Yarn as its package manager.

Code Quality Tests live alongside a shared tests/AllLoaders.test.tsx that iterates every named export from src/index.ts and asserts three behaviors common to all loaders — rendering nothing when loading is false, honoring cssOverride, and passing through arbitrary HTML/ARIA props — avoiding 23 near-duplicate test files. The shared helpers (animation.ts, unitConverter.ts, colors.ts) each carry their own dedicated unit tests using Jest, ts-jest, and Testing Library. Linting runs through a modern flat ESLint config with TypeScript, Testing Library, and jest-dom plugins, and CI (GitHub Actions) runs lint and test jobs with --max-warnings=0 on every push and pull request, plus Coveralls coverage reporting — a well-disciplined setup for a component library of this size.

API Design Every loader shares an identical prop contract (loading, color, cssOverride, speedMultiplier, plus shape-appropriate sizing props), so switching between any of the 23 components requires no relearning. Size-related props accept either a bare number (defaulting to px) or a string with an explicit CSS unit, validated against a fixed allow-list with a console warning on invalid input rather than a silent failure or thrown error. Unrecognized props are spread onto the rendered element, so consumers get standard HTML/ARIA passthrough for free. The design favors predictability and low boilerplate over novel technical mechanisms — the animations themselves are standard CSS keyframes, so the library’s value lies in ergonomics and consistency rather than a new rendering technique.