https://github.com/agneym/react-loading
Accessible and Simple Loading indicators in React
https://github.com/agneym/react-loading
react
Last synced: about 1 year ago
JSON representation
Accessible and Simple Loading indicators in React
- Host: GitHub
- URL: https://github.com/agneym/react-loading
- Owner: agneym
- License: mit
- Created: 2020-10-04T09:15:16.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-06-04T17:02:00.000Z (about 5 years ago)
- Last Synced: 2024-09-30T10:08:01.000Z (almost 2 years ago)
- Topics: react
- Language: TypeScript
- Homepage: https://agneym.github.io/react-loading/
- Size: 1.69 MB
- Stars: 64
- Watchers: 4
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
React Loading
Simple and Accessible loading indicators with React.
Comes bundled with React components of [Sam Herbert's animated SVG loaders](https://github.com/SamHerbert/SVG-Loaders) in a tree shakeable package.
## Installation
```bash
npm i @agney/react-loading
# OR
yarn add @agney/react-loading
```
[Demo](https://agneym.github.io/react-loading/)
## Features
- **Small Size**
The entire library is about [20kB minified](https://bundlephobia.com/result?p=@agney/react-loading). _But you would never need the whole bundle._
The library is build to be treeshakeable that when you use one or two of the bundled loaders, you would have **less than 1kB** in your bundle.
No dependencies either 😇
- **Accessibility**
Provides accessibility attributes on your loading components and containers.
`aria-busy` is set to `true` on container on loading and progress indicators have `role=progressbar`.
- **Specify a Global loader**
You probably don't want loader components mixed everywhere, so you can specify a `LoaderContext` that can be overridden later if necessary.
- **Bring your own loader**
If you decide to bring your own loading indicator, library would support that as well, keeping all your logic the same.
- TypeScript support. Zero extra CSS.
## Usage
```javascript
import { useLoading, Audio } from '@agney/react-loading';
function Content() {
const { containerProps, indicatorEl } = useLoading({
loading: true,
indicator: ,
});
return (
{/* Accessibility props injected to container */}
{indicatorEl} {/* renders only while loading */}
);
}
```
[Sample](https://codesandbox.io/s/agneyreact-loading-example-9jj7c)
## Loaders
This library comes bundled with React components of [Sam Herbert's animated SVG loaders](https://github.com/SamHerbert/SVG-Loaders) in a tree shakeable package.
Each loader is an SVG and all props passed shall be applied to the top SVG element. All SVGs are set to inherit `currentColor` from it's parents for fill/stroke.
Available loaders are:
```javascript
import {
Audio,
BallTriangle,
Bars,
Circles,
Grid,
Hearts,
Oval,
Puff,
Rings,
SpinningCircles,
TailSpin,
ThreeDots,
} from '@agney/react-loading';
```
Only the ones you use will be included in your bundle when you use a bundler like Webpack/Rollup.
## Context
You can specify a single loading indicator reused across hooks with the `LoaderProvider`.
```javascript
import { LoaderProvider, useLoading, BallTriangle } from '@agney/react-loading';
function App() {
const { containerProps, indicatorEl } = useLoading({
loading: true,
});
return {indicatorEl};
}
ReactDOM.render(
}>
);
```
You can use as many `LoaderProvider` provider elements as you like and React will pick the one closest to the hook you are rendering.
[More on React Context](https://reactjs.org/docs/context.html)
## Extra Props on Loader
If you want to provide specific props on a loader specifically when you use the hook:
```javascript
useLoading({
loading: true,
loaderProps: {
// Any props here would be spread on to the indicator element.
style: {{ margin: '0 auto' }}
}
});
```
We also a provide a special key for `valueText`, that will be used as description for indicator:
```javascript
useLoading({
loading: true,
loaderProps: {
valueText: 'Fetching video from the Great Internet',
},
});
// now this will generate:
/* */
```
`aria-valuetext` will be read by screenreaders.
You could also provide `aria-valuenow` for indicators that display progress (but the prebundled ones are best for indeterminate progress indicators)
[MDN for Reference on `progressbar`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_progressbar_role)
## Bring your own loader
Just switch the import to your own loading indicator (just make sure that it accepts props)
```javascript
import { LoaderProvider, useLoading } from '@agney/react-loading';
const Loader = ({ ...rest }) =>
Loading...
;
function App() {
const { containerProps, indicatorEl } = useLoading({
loading: true,
});
return {indicatorEl};
}
ReactDOM.render(
}>
);
```
# Contributing
All PRs welcome.
## Development
We use [`tsdx`](https://github.com/formium/tsdx) for generating boilerplate.
**Install:**
```bash
# Library
npm i
# Example
cd example && npm i
```
**Development:**
```bash
# Running library dev
npm start
# Running example
cd example && npm start
```
**Testing:**
Testing with `react-testing-library` and `jest`
```bash
npm test
```
Commands are available in detail on tsdx repository.
# Credits
- [Sam Herbert](http://samherbert.net/) for the amazing SVGs