Skip to content

Commit 366fac5

Browse files
mhnpdmhnpd
committed
refactor: enhance README.md for improved clarity and structure; update installation instructions and usage examples
1 parent fa47ee4 commit 366fac5

1 file changed

Lines changed: 230 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 230 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,262 @@
1-
![release](https://badgen.net/github/release/mhnpd/react-loader-spinner)
2-
![tag](https://badgen.net/github/tag/mhnpd/react-loader-spinner)
3-
![stars](https://badgen.net/github/stars/mhnpd/react-loader-spinner)
4-
![issue](https://badgen.net/github/issues/mhnpd/react-loader-spinner)
5-
![open-issues](https://badgen.net/github/open-issues/mhnpd/react-loader-spinner)
6-
![commits](https://badgen.net/github/commits/mhnpd/react-loader-spinner)
7-
![commits](https://badgen.net/github/assets-dl/mhnpd/react-loader-spinner)
8-
9-
<div style="text-align:center;">
10-
<p>
11-
<img src="/logo/logo.png" alt="title"/>
12-
</p>
1+
<div align="center">
2+
<img src="/logo/logo.png" alt="React Loader Spinner" width="200"/>
3+
4+
# React Loader Spinner
5+
6+
[![npm version](https://badgen.net/npm/v/react-loader-spinner)](https://www.npmjs.com/package/react-loader-spinner)
7+
[![downloads](https://badgen.net/npm/dt/react-loader-spinner)](https://www.npmjs.com/package/react-loader-spinner)
8+
![stars](https://badgen.net/github/stars/mhnpd/react-loader-spinner)
9+
![release](https://badgen.net/github/release/mhnpd/react-loader-spinner)
10+
![issues](https://badgen.net/github/open-issues/mhnpd/react-loader-spinner)
11+
![license](https://badgen.net/github/license/mhnpd/react-loader-spinner)
12+
13+
**Simple, lightweight React SVG spinner components**
14+
Perfect for async operations and loading states
15+
16+
[📚 Documentation](https://mhnpd.github.io/react-loader-spinner/) • [🎨 Live Demo](https://mhnpd.github.io/react-loader-spinner/docs/category/components/) • [💻 CodeSandbox](https://codesandbox.io/p/sandbox/react-loader-spinner-86zm9s)
17+
1318
</div>
1419

15-
`react-loader-spinner` provides simple React SVG spinner components which can be implemented for async/await operations before data loads in the view.
20+
---
21+
22+
## ✨ Features
23+
24+
- 🎯 **35+ Beautiful Spinners** - Wide variety of loading animations
25+
- 🎨 **Fully Customizable** - Colors, sizes, and styles
26+
- 📦 **Lightweight** - Zero dependencies (except React)
27+
- 🌲 **Tree-shakeable** - Import only what you need
28+
- 💪 **TypeScript** - Full type definitions included
29+
- ⚡ **React 17, 18 & 19** - Compatible with all modern React versions
30+
- 🎭 **No CSS Required** - Pure SVG animations
31+
- ♿ **Accessible** - ARIA labels and semantic HTML
32+
33+
## 📦 Installation
34+
35+
```bash
36+
npm install react-loader-spinner
37+
```
1638

17-
### Installation
39+
Or using yarn:
1840

1941
```bash
20-
npm install react-loader-spinner --save
21-
# or
2242
yarn add react-loader-spinner
2343
```
2444

25-
### Documentation:
45+
## 🚀 Quick Start
46+
47+
```jsx
48+
import { Audio } from 'react-loader-spinner'
49+
50+
function App() {
51+
return (
52+
<Audio
53+
height="80"
54+
width="80"
55+
color="#4fa94d"
56+
ariaLabel="audio-loading"
57+
wrapperStyle={{}}
58+
wrapperClass="wrapper-class"
59+
visible={true}
60+
/>
61+
)
62+
}
63+
```
64+
65+
## 📖 Documentation
2666

27-
1. [Getting Started](https://mhnpd.github.io/react-loader-spinner/docs/intro)
28-
2. [Spinners](https://mhnpd.github.io/react-loader-spinner/docs/category/components/)
29-
3. [Code Sandbox Example](https://codesandbox.io/p/sandbox/react-loader-spinner-86zm9s?file=%2Fsrc%2Fstyles.css%3A8%2C23&layout=%257B%2522sidebarPanel%2522%253A%2522EXPLORER%2522%252C%2522rootPanelGroup%2522%253A%257B%2522direction%2522%253A%2522horizontal%2522%252C%2522contentType%2522%253A%2522UNKNOWN%2522%252C%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522id%2522%253A%2522ROOT_LAYOUT%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522UNKNOWN%2522%252C%2522direction%2522%253A%2522vertical%2522%252C%2522id%2522%253A%2522clqggrep400063p6gzbl599ai%2522%252C%2522sizes%2522%253A%255B100%252C0%255D%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522EDITOR%2522%252C%2522direction%2522%253A%2522horizontal%2522%252C%2522id%2522%253A%2522EDITOR%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL%2522%252C%2522contentType%2522%253A%2522EDITOR%2522%252C%2522id%2522%253A%2522clqggrep400023p6ghzsimx31%2522%257D%255D%257D%252C%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522SHELLS%2522%252C%2522direction%2522%253A%2522horizontal%2522%252C%2522id%2522%253A%2522SHELLS%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL%2522%252C%2522contentType%2522%253A%2522SHELLS%2522%252C%2522id%2522%253A%2522clqggrep400033p6g3eer5i1g%2522%257D%255D%252C%2522sizes%2522%253A%255B100%255D%257D%255D%257D%252C%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522DEVTOOLS%2522%252C%2522direction%2522%253A%2522vertical%2522%252C%2522id%2522%253A%2522DEVTOOLS%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL%2522%252C%2522contentType%2522%253A%2522DEVTOOLS%2522%252C%2522id%2522%253A%2522clqggrep400053p6gnojd5tz3%2522%257D%255D%252C%2522sizes%2522%253A%255B100%255D%257D%255D%252C%2522sizes%2522%253A%255B53.65943417458956%252C46.34056582541044%255D%257D%252C%2522tabbedPanels%2522%253A%257B%2522clqggrep400023p6ghzsimx31%2522%253A%257B%2522id%2522%253A%2522clqggrep400023p6ghzsimx31%2522%252C%2522tabs%2522%253A%255B%257B%2522id%2522%253A%2522clqgh245x00023p6gdkh2fmc9%2522%252C%2522mode%2522%253A%2522permanent%2522%252C%2522type%2522%253A%2522FILE%2522%252C%2522initialSelections%2522%253A%255B%257B%2522startLineNumber%2522%253A16%252C%2522startColumn%2522%253A19%252C%2522endLineNumber%2522%253A16%252C%2522endColumn%2522%253A19%257D%255D%252C%2522filepath%2522%253A%2522%252Fsrc%252FApp.js%2522%252C%2522state%2522%253A%2522IDLE%2522%257D%252C%257B%2522id%2522%253A%2522clqgh5glr00023p6gb7gaz27h%2522%252C%2522mode%2522%253A%2522permanent%2522%252C%2522type%2522%253A%2522FILE%2522%252C%2522initialSelections%2522%253A%255B%257B%2522startLineNumber%2522%253A8%252C%2522startColumn%2522%253A23%252C%2522endLineNumber%2522%253A8%252C%2522endColumn%2522%253A23%257D%255D%252C%2522filepath%2522%253A%2522%252Fsrc%252Fstyles.css%2522%252C%2522state%2522%253A%2522IDLE%2522%257D%255D%252C%2522activeTabId%2522%253A%2522clqgh5glr00023p6gb7gaz27h%2522%257D%252C%2522clqggrep400053p6gnojd5tz3%2522%253A%257B%2522id%2522%253A%2522clqggrep400053p6gnojd5tz3%2522%252C%2522activeTabId%2522%253A%2522clqghx88q001i3p6gpjtn1qsu%2522%252C%2522tabs%2522%253A%255B%257B%2522type%2522%253A%2522UNASSIGNED_PORT%2522%252C%2522port%2522%253A0%252C%2522id%2522%253A%2522clqghx88q001i3p6gpjtn1qsu%2522%252C%2522mode%2522%253A%2522permanent%2522%252C%2522path%2522%253A%2522%252F%2522%257D%255D%257D%252C%2522clqggrep400033p6g3eer5i1g%2522%253A%257B%2522tabs%2522%253A%255B%255D%252C%2522id%2522%253A%2522clqggrep400033p6g3eer5i1g%2522%257D%257D%252C%2522showDevtools%2522%253Atrue%252C%2522showShells%2522%253Afalse%252C%2522showSidebar%2522%253Atrue%252C%2522sidebarPanelSize%2522%253A15%257D)
67+
Visit our **[complete documentation](https://mhnpd.github.io/react-loader-spinner/)** for:
3068

31-
### Usage
69+
- **[Getting Started Guide](https://mhnpd.github.io/react-loader-spinner/docs/intro)** - Installation and basic usage
70+
- **[All Components](https://mhnpd.github.io/react-loader-spinner/docs/category/components/)** - Browse all 35+ spinner components
71+
- **[API Reference](https://mhnpd.github.io/react-loader-spinner/docs/intro)** - Detailed prop documentation
72+
- **[Live Examples](https://mhnpd.github.io/react-loader-spinner/docs/category/components/)** - Interactive demos
3273

33-
> No css import is required
74+
## 🎨 Available Spinners
75+
76+
<details>
77+
<summary><b>View all 35+ spinners</b></summary>
78+
79+
- Audio
80+
- Ball Triangle
81+
- Bars
82+
- Blocks
83+
- Circles
84+
- Circles With Bar
85+
- Circular Progress
86+
- Color Ring
87+
- Comment
88+
- Discuss
89+
- DNA
90+
- Falling Lines
91+
- Fidget Spinner
92+
- Grid
93+
- Hearts
94+
- Hourglass
95+
- Infinity Spin
96+
- Line Wave
97+
- Magnifying Glass
98+
- Mutating Dots
99+
- Oval
100+
- Progress Bar
101+
- Puff
102+
- Radio
103+
- Revolving Dot
104+
- Rings
105+
- Rotating Lines
106+
- Rotating Square
107+
- Rotating Triangles
108+
- Tail Spin
109+
- Three Circles
110+
- Three Dots
111+
- Triangle
112+
- Vortex
113+
- Watch
114+
115+
</details>
116+
117+
## 💡 Usage Examples
118+
119+
### Basic Usage
34120

35121
```jsx
36-
import { Audio } from 'react-loader-spinner';
122+
import { Oval } from 'react-loader-spinner'
37123

38-
<Audio
124+
;<Oval
125+
height={80}
126+
width={80}
127+
color="#4fa94d"
128+
visible={true}
129+
ariaLabel="oval-loading"
130+
secondaryColor="#4fa94d"
131+
strokeWidth={2}
132+
strokeWidthSecondary={2}
133+
/>
134+
```
135+
136+
### With Custom Styling
137+
138+
```jsx
139+
import { ThreeDots } from 'react-loader-spinner'
140+
141+
;<ThreeDots
39142
height="80"
40143
width="80"
41144
radius="9"
42-
color="green"
43-
ariaLabel="loading"
44-
/>
45-
wrapperStyle
46-
wrapperClass
145+
color="#4fa94d"
146+
ariaLabel="three-dots-loading"
147+
wrapperStyle={{ margin: '20px' }}
148+
wrapperClass="custom-loader"
149+
visible={true}
47150
/>
48151
```
49152

50-
#### Individual (deep) imports
153+
### Conditional Rendering
51154

52-
Each loader can also be imported directly (useful for some bundlers / tree‑shaking scenarios):
155+
```jsx
156+
import { TailSpin } from 'react-loader-spinner'
157+
158+
function MyComponent() {
159+
const [loading, setLoading] = useState(true)
160+
161+
return (
162+
<div>
163+
<TailSpin
164+
height="80"
165+
width="80"
166+
color="#4fa94d"
167+
ariaLabel="tail-spin-loading"
168+
visible={loading}
169+
/>
170+
</div>
171+
)
172+
}
173+
```
174+
175+
### Tree-shaking with Direct Imports
176+
177+
For optimal bundle size, import components directly:
53178

54179
```jsx
55-
import { Audio } from 'react-loader-spinner/audio'
180+
// Direct import (better for tree-shaking)
181+
import { Audio } from 'react-loader-spinner/dist/esm/loader/audio'
182+
183+
// Or use named imports (also tree-shakeable)
184+
import { Audio, Oval, ThreeDots } from 'react-loader-spinner'
185+
```
186+
187+
## 🎯 Common Props
188+
189+
All spinner components accept these common props:
190+
191+
| Prop | Type | Default | Description |
192+
| -------------- | ------------------ | ------------------ | ------------------------- |
193+
| `height` | `string \| number` | `"100"` | Height of the spinner |
194+
| `width` | `string \| number` | `"100"` | Width of the spinner |
195+
| `color` | `string` | `"#4fa94d"` | Primary color |
196+
| `visible` | `boolean` | `true` | Show/hide the spinner |
197+
| `ariaLabel` | `string` | Component-specific | Accessibility label |
198+
| `wrapperStyle` | `CSSProperties` | `{}` | Inline styles for wrapper |
199+
| `wrapperClass` | `string` | `""` | CSS class for wrapper |
200+
201+
> **Note:** Individual components may have additional specific props. Check the [documentation](https://mhnpd.github.io/react-loader-spinner/docs/category/components/) for each component.
202+
203+
## 🔧 TypeScript Support
204+
205+
This package includes TypeScript definitions out of the box:
56206

57-
// other examples:
58-
// import { Oval } from 'react-loader-spinner/oval'
59-
// import { ThreeDots } from 'react-loader-spinner/three-dots'
207+
```tsx
208+
import { Audio } from 'react-loader-spinner'
209+
import type { CSSProperties } from 'react'
210+
211+
const wrapperStyle: CSSProperties = {
212+
display: 'flex',
213+
justifyContent: 'center',
214+
}
215+
216+
;<Audio height="80" width="80" color="blue" wrapperStyle={wrapperStyle} />
60217
```
61218

62-
## License
219+
## 🌐 Browser Support
220+
221+
- ✅ Chrome (latest)
222+
- ✅ Firefox (latest)
223+
- ✅ Safari (latest)
224+
- ✅ Edge (latest)
225+
- ✅ Modern mobile browsers
226+
227+
## 🤝 Contributing
228+
229+
We welcome contributions! Please see our [Contributing Guide](./Contributing.md) for details.
230+
231+
1. Fork the repository
232+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
233+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
234+
4. Push to the branch (`git push origin feature/amazing-feature`)
235+
5. Open a Pull Request
236+
237+
## 📝 License
63238

64-
MIT
239+
MIT © [Mohan Upadhyay](https://mohanpd.com.np)
65240

66-
## Contributors
241+
## 🙏 Contributors
242+
243+
Thanks goes to these wonderful people:
67244

68245
<a href="https://github.com/mhnpd/react-loader-spinner/graphs/contributors">
69246
<img src="https://contrib.rocks/image?repo=mhnpd/react-loader-spinner" />
70247
</a>
248+
249+
## 🔗 Links
250+
251+
- [📚 Full Documentation](https://mhnpd.github.io/react-loader-spinner/)
252+
- [🐛 Report Bug](https://github.com/mhnpd/react-loader-spinner/issues)
253+
- [💡 Request Feature](https://github.com/mhnpd/react-loader-spinner/issues)
254+
- [📦 npm Package](https://www.npmjs.com/package/react-loader-spinner)
255+
256+
---
257+
258+
<div align="center">
259+
Made with ❤️ by <a href="https://mohanpd.com.np">Mohan Upadhyay</a>
260+
261+
⭐ Star us on GitHub — it helps!
262+
</div>

0 commit comments

Comments
 (0)