Registry / web-framework / react-spinners

react-spinners

library0.17.0jsnpmunverified

React Spinners is a comprehensive collection of declarative, customizable loading spinner components designed for React applications. Currently stable at version 0.17.0, it offers a diverse range of animated loaders to provide visual feedback during asynchronous operations. The library maintains an active development and release cadence, consistently delivering updates, bug fixes, and performance improvements. A significant distinguishing feature, introduced in version 0.13.0, is its complete elimination of external runtime dependencies, drastically reducing bundle size and improving overall project footprint. It provides robust TypeScript support, integrates seamlessly with modern React ecosystems, supports React versions from 16 through 19, and is optimized for tree-shaking.

web-framework

npm install react-spinners

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-SPINNERS

react-spinners

web-frameworkjavascriptv0.17.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ClipLoader

✓ import { ClipLoader } from 'react-spinners';

✗ const ClipLoader = require('react-spinners');

The library primarily uses ES Module exports. CommonJS require() is generally discouraged for modern React projects and might lead to issues with tree-shaking or module resolution.

ScaleLoader

✓ import { ScaleLoader } from 'react-spinners';

✗ import ScaleLoader from 'react-spinners';

All loader components are named exports, not default exports. Attempting to use a default import will result in 'undefined' or a module error.

DotLoader

✓ import { DotLoader } from 'react-spinners';

✗ import { DotLoader, RingLoader } from 'react-spinners/dist/DotLoader';

All individual loaders are directly available as named exports from the top-level 'react-spinners' package. Avoid importing from deep paths like 'dist/' unless specifically advised for legacy reasons.

Demonstrates how to import and use the ClipLoader component with state management for loading and color props, including CSS overrides.

import { useState, CSSProperties } from "react"; import { ClipLoader } from "react-spinners"; const override: CSSProperties = { display: "block", margin: "0 auto", borderColor: "red" }; function App() { let [loading, setLoading] = useState(true); let [color, setColor] = useState("#ffffff"); return ( <div className="sweet-loading"> <button onClick={() => setLoading(!loading)}>Toggle Loader</button> <input value={color} onChange={(e) => setColor(e.target.value)} placeholder="Color of the loader" /> <ClipLoader color={color} loading={loading} cssOverride={override} size={150} aria-label="Loading Spinner" data-testid="loader" /> </div> ); } export default App;

Debug

Known issues

breakingVersion 0.16.0 introduced a breaking change where the `barCount` prop for `ScaleLoader` became mandatory. This was an unintended change.

fix

Upgrade to `react-spinners@0.16.1` or higher, which reverts `barCount` to an optional prop. Alternatively, explicitly provide the `barCount` prop when using `ScaleLoader` in version `0.16.0`.

affects: 0.16.0

gotchaPrior to version 0.17.0, `react-spinners` components might not have functioned correctly or required manual client component directives when used directly within React Server Components (RSC) contexts.

fix

Upgrade to `react-spinners@0.17.0` or higher, which includes `"use client"` directives to ensure compatibility with RSC. For older versions, wrap spinner components in a client component or ensure their parent is marked as client-side.

affects: <0.17.0

gotchaVersion 0.17.0 removed UMD and duplicated CommonJS files from the published package to reduce its total size. While beneficial for most, users with highly specific or legacy CommonJS build configurations might encounter changes in module resolution or bundling behavior.

fix

Verify your build setup handles ES Module imports correctly. For legacy CommonJS environments, ensure your bundler (e.g., Webpack, Rollup) is configured to transpile or resolve ES Modules from `node_modules`.

affects: >=0.17.0

gotchaA bug in `react-spinners` versions 0.14.0 and 0.14.1 caused multiple `HashLoader` instances with different `color` props to render with the same color, due to a fix being introduced and then immediately reverted.

fix

To avoid the `HashLoader` color consistency bug, use `react-spinners@0.13.x` or upgrade to `react-spinners@0.15.0` or higher.

affects: 0.14.0, 0.14.1

gotchaVersion 0.13.0 underwent a major refactor, removing `@emotion/react` as a dependency and rewriting all components as functional components. This change drastically reduced the library's bundle size and removed an external styling engine dependency.

fix

No direct fix needed, but be aware of the internal architectural change. If you previously had custom Emotion configurations interacting with `react-spinners`, those integrations might need review or removal as the library no longer uses Emotion.

affects: >=0.13.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'barCount')

Attempting to use `ScaleLoader` from `react-spinners@0.16.0` without providing the required `barCount` prop.

fix

Upgrade to `react-spinners@0.16.1` or higher, or explicitly pass a `barCount` prop (e.g., `<ScaleLoader barCount={5} />`) if locked to `v0.16.0`.

ReferenceError: require is not defined

Attempting to import `react-spinners` components using CommonJS `require()` syntax in an ES Module-only environment (e.g., a modern React app or a Next.js App Router component).

fix

Use ES Module named imports: `import { ClipLoader } from 'react-spinners';` instead of `const ClipLoader = require('react-spinners');`.

Error: Hydration failed because the initial UI does not match what was rendered on the server.

Using `react-spinners` components directly in a React Server Component (RSC) without them being marked as client components, leading to a mismatch between server-rendered and client-hydrated content.

fix

Upgrade to `react-spinners@0.17.0` or higher, which includes necessary `"use client"` directives. For older versions, explicitly make the component a client component by adding `'use client';` at the top of its file, or render the spinner within a client-side wrapper component.

All HashLoader components render with the same color, despite being passed different 'color' props.

This is a known bug specifically present in `react-spinners@0.14.0` and `react-spinners@0.14.1` related to `HashLoader`'s color management.

fix

Downgrade to `react-spinners@0.13.x` or upgrade to `react-spinners@0.15.0` or newer to resolve this `HashLoader` specific coloring issue.

Upgrade

Version history

0.17.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for rendering React components.

react-domrequiredPeer dependency required for rendering React components into the DOM.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/davidhu2000/react-spinners ↗

packagehttps://www.npmjs.com/package/react-spinners ↗

homepagehttps://www.davidhu.io/react-spinners ↗