React Spinners

Common errors

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

  cause 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

  cause 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.

  cause 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.

  cause 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.

Warnings

• breaking Version 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`.
• gotcha Prior 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.
• gotcha Version 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`.
• gotcha A 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.
• gotcha Version 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.

Install

• npm install react-spinners npm
• yarn add react-spinners yarn
• pnpm add react-spinners pnpm

Imports

• ClipLoader
  wrong:

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

  correct:

  import { ClipLoader } from '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
  wrong:

  import ScaleLoader from 'react-spinners';

  correct:

  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
  wrong:

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

  correct:

  import { DotLoader } from 'react-spinners';

  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.

Quickstart

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;