0
# React Spinners
1

2
React Spinners is a comprehensive collection of customizable loading spinner components for React applications. It offers 23 different animated spinner types including ClipLoader, BeatLoader, RingLoader, and many others. Built with TypeScript and zero dependencies, the library provides a consistent API where each spinner accepts common props like `loading`, `color`, `cssOverride`, and `speedMultiplier`, along with spinner-specific sizing properties.
3

4
## Package Information
5

6
- **Package Name**: react-spinners
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-spinners`
10
- **Zero Dependencies**: No external runtime dependencies
11
- **Tree Shaking**: Full ESM support for optimal bundle sizes
12

13
## Core Imports
14

15
```typescript
16
import { ClipLoader, BeatLoader, BarLoader } from "react-spinners";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { ClipLoader, BeatLoader, BarLoader } = require("react-spinners");
23
```
24

25
Individual imports for better tree shaking:
26

27
```typescript
28
import ClipLoader from "react-spinners/ClipLoader";
29
import BeatLoader from "react-spinners/BeatLoader";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import React, { useState } from "react";
36
import { ClipLoader } from "react-spinners";
37

38
function App() {
39
  const [loading, setLoading] = useState(true);
40

41
  return (
42
    <div>
43
      <ClipLoader
44
        loading={loading}
45
        color="#36d7b7"
46
        size={50}
47
        aria-label="Loading Spinner"
48
        data-testid="loader"
49
      />
50
      <button onClick={() => setLoading(!loading)}>
51
        Toggle Loading
52
      </button>
53
    </div>
54
  );
55
}
56
```
57

58
## Architecture
59

60
React Spinners is built around several key design principles:
61

62
- **Consistent API**: All components share common props for color, loading state, and styling
63
- **TypeScript-First**: Full type safety with comprehensive prop interfaces
64
- **CSS-in-JS**: No external stylesheets required, all styling is inline with dynamic keyframe generation
65
- **Conditional Rendering**: Components return `null` when `loading={false}` for easy show/hide control
66
- **Accessibility Ready**: Full support for ARIA attributes and semantic HTML
67
- **Server-Side Rendering**: Compatible with Next.js and other SSR frameworks
68

69
## Common Props
70

71
All spinner components accept these shared properties:
72

73
```typescript { .api }
74
interface CommonProps {
75
  /** Controls spinner visibility, returns null when false */
76
  loading?: boolean;
77
  /** Spinner color as hex, RGB, RGBA, or named color */
78
  color?: string;
79
  /** Custom CSS styles applied to spinner container */
80
  cssOverride?: CSSProperties;
81
  /** Speed multiplier for animation (1 = normal, 0.5 = half speed, 2 = double speed) */
82
  speedMultiplier?: number;
83
  /** All standard HTML span element attributes are supported */
84
  [key: string]: any;
85
}
86
```
87

88
## Capabilities
89

90
### Circular and Ring Spinners
91

92
Circular loading indicators with various animation patterns, perfect for general loading states and button spinners.
93

94
```typescript { .api }
95
// Circular spinners with size-based props
96
interface LoaderSizeProps extends CommonProps {
97
  size?: LengthType;
98
}
99

100
function ClipLoader(props: LoaderSizeProps): JSX.Element | null;
101
function CircleLoader(props: LoaderSizeProps): JSX.Element | null;
102
function ClockLoader(props: LoaderSizeProps): JSX.Element | null;
103
function RingLoader(props: LoaderSizeProps): JSX.Element | null;
104
function BounceLoader(props: LoaderSizeProps): JSX.Element | null;
105
function PuffLoader(props: LoaderSizeProps): JSX.Element | null;
106
function SquareLoader(props: LoaderSizeProps): JSX.Element | null;
107
function SkewLoader(props: LoaderSizeProps): JSX.Element | null;
108
function MoonLoader(props: LoaderSizeProps): JSX.Element | null;
109
function HashLoader(props: LoaderSizeProps): JSX.Element | null;
110
function DotLoader(props: LoaderSizeProps): JSX.Element | null;
111
```
112

113
[Circular Spinners](./circular-spinners.md)
114

115
### Dot and Beat Spinners
116

117
Multi-dot animations with configurable spacing, ideal for subtle loading indicators and inline progress display.
118

119
```typescript { .api }
120
// Dot-based spinners with size and margin props
121
interface LoaderSizeMarginProps extends CommonProps {
122
  size?: LengthType;
123
  margin?: LengthType;
124
}
125

126
function BeatLoader(props: LoaderSizeMarginProps): JSX.Element | null;
127
function PulseLoader(props: LoaderSizeMarginProps): JSX.Element | null;
128
function SyncLoader(props: LoaderSizeMarginProps): JSX.Element | null;
129
function RiseLoader(props: LoaderSizeMarginProps): JSX.Element | null;
130
function RotateLoader(props: LoaderSizeMarginProps): JSX.Element | null;
131
function GridLoader(props: LoaderSizeMarginProps): JSX.Element | null;
132
```
133

134
[Dot and Beat Spinners](./dot-beat-spinners.md)
135

136
### Bar and Linear Spinners
137

138
Linear progress indicators and bar animations, perfect for form submissions and content loading states.
139

140
```typescript { .api }
141
// Height/width-based spinners
142
interface LoaderHeightWidthProps extends CommonProps {
143
  height?: LengthType;
144
  width?: LengthType;
145
}
146

147
function BarLoader(props: LoaderHeightWidthProps): JSX.Element | null;
148

149
// Bar spinners with radius and margin control  
150
interface LoaderHeightWidthRadiusProps extends CommonProps {
151
  height?: LengthType;
152
  width?: LengthType;
153
  radius?: LengthType;
154
  margin?: LengthType;
155
}
156

157
function FadeLoader(props: LoaderHeightWidthRadiusProps): JSX.Element | null;
158
```
159

160
[Bar and Linear Spinners](./bar-linear-spinners.md)
161

162
### Specialty and Themed Spinners
163

164
Unique animations with distinctive visual styles, great for branded loading experiences and specific use cases.
165

166
```typescript { .api }
167
function PacmanLoader(props: LoaderSizeMarginProps): JSX.Element | null;
168
function ClimbingBoxLoader(props: LoaderSizeProps): JSX.Element | null;
169
function PropagateLoader(props: LoaderSizeProps): JSX.Element | null;
170

171
// ScaleLoader with configurable bar count
172
interface ScaleLoaderProps extends LoaderHeightWidthRadiusProps {
173
  barCount?: number;
174
}
175

176
function ScaleLoader(props: ScaleLoaderProps): JSX.Element | null;
177
```
178

179
[Specialty Spinners](./specialty-spinners.md)
180

181
## Types
182

183
```typescript { .api }
184
// Base length type for all size-related props
185
type LengthType = number | string;
186

187
// Base props extended by all spinner components
188
interface CommonProps extends DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> {
189
  loading?: boolean;
190
  color?: string;
191
  cssOverride?: CSSProperties;
192
  speedMultiplier?: number;
193
}
194

195
// Prop interfaces for different spinner categories
196
interface LoaderSizeProps extends CommonProps {
197
  size?: LengthType;
198
}
199

200
interface LoaderSizeMarginProps extends CommonProps {
201
  size?: LengthType;
202
  margin?: LengthType;
203
}
204

205
interface LoaderHeightWidthProps extends CommonProps {
206
  height?: LengthType;
207
  width?: LengthType;
208
}
209

210
interface LoaderHeightWidthRadiusProps extends CommonProps {
211
  height?: LengthType;
212
  width?: LengthType;
213
  radius?: LengthType;
214
  margin?: LengthType;
215
}
216
```