mirror of
https://github.com/zhigang1992/react-content-loader.git
synced 2026-05-13 02:02:00 +08:00
b8e5cb9e8c
* feat(svg): add an interval prop Add an interval prop that controls the duration of the interval between two animations. For instance, an interval of `.25` and an animation speed of `2` imply that the animation will take 1.5s to complete, and wait 0.5s before starting again. * feat(svg): add a gradientRatio prop Add a gradientRatio prop that controls the width of the gradient relative to the viewbox's own width. For instance, a gradientRatio of `0.5` and a width of `200` imply that the resulting gradient will have a width of 100px. * docs(docz): add props section
276 lines
8.3 KiB
Markdown
Executable File
276 lines
8.3 KiB
Markdown
Executable File
<p align="center">
|
|
<img width="350" alt="react-content-loader" src="https://user-images.githubusercontent.com/4838076/34419335-5669c3f8-ebea-11e7-9668-c47b7846970b.png"/>
|
|
</p>
|
|
<p align="center">
|
|
<img width="400" alt="Example's react-content-loader" src="https://user-images.githubusercontent.com/4838076/34308760-ec55df82-e735-11e7-843b-2e311fa7b7d0.gif" />
|
|
</p>
|
|
|
|
SVG-Powered component to easily create placeholder loadings (like Facebook's cards loading).
|
|
|
|
## Features
|
|
|
|
- :gear: **Customizable:** Feel free to change the colors, speed, sizes and even **RTL**;
|
|
- :ok_hand: **Plug and play:** with many presets to use, see the [examples](#examples);
|
|
- :pencil2: **DIY:** use the [create-content-loader](https://danilowoz.github.io/create-content-loader/) to create your own custom loaders easily;
|
|
- ⚛️ **Lightweight:** only **1.4kB** gzipped and **0 dependencies**;
|
|
|
|
## Index
|
|
|
|
- [Getting Started](#getting-started)
|
|
- [Usage](#usage)
|
|
- [Options](#options)
|
|
- [Examples](#examples)
|
|
- [Similar packages](#similar-packages)
|
|
- [Development](#development)
|
|
- [Known Issues](#known-issues)
|
|
|
|
## Getting Started
|
|
|
|
```sh
|
|
npm i react-content-loader --save
|
|
```
|
|
|
|
```sh
|
|
yarn add react-content-loader
|
|
```
|
|
|
|
CDN from [JSDELIVR](https://www.jsdelivr.com/package/npm/react-content-loader)
|
|
|
|
## Usage
|
|
|
|
There are two ways to use it:
|
|
|
|
**1. Presets, see the [examples](#examples):**
|
|
|
|
```jsx
|
|
import ContentLoader, { Facebook } from 'react-content-loader'
|
|
|
|
const MyLoader = () => <ContentLoader />
|
|
const MyFacebookLoader = () => <Facebook />
|
|
```
|
|
|
|
**2. Custom mode, see the [online tool](https://danilowoz.github.io/create-react-content-loader/)**
|
|
|
|
```jsx
|
|
const MyLoader = () => (
|
|
<ContentLoader>
|
|
{/* Only SVG shapes */}
|
|
<rect x="0" y="0" rx="5" ry="5" width="70" height="70" />
|
|
<rect x="80" y="17" rx="4" ry="4" width="300" height="13" />
|
|
<rect x="80" y="40" rx="3" ry="3" width="250" height="10" />
|
|
</ContentLoader>
|
|
)
|
|
```
|
|
|
|
**Still not clear?** Take a look at this working example at [codesandbox.io](https://codesandbox.io/s/moojk887z9)
|
|
|
|
## Options
|
|
|
|
**`animate?: boolean`**
|
|
|
|
Defaults to `true`. Opt-out of animations with `false`
|
|
|
|
**`ariaLabel? string | boolean`**
|
|
|
|
Defaults to `Loading interface...`. It's used to describe what element it is. Use `false` to remove.
|
|
|
|
**`speed?: number`**
|
|
|
|
Defaults to `2`. Animation speed in seconds.
|
|
|
|
**`interval?: number`**
|
|
|
|
Defaults to `0.25`. Interval of time between runs of the animation, as a fraction of the animation speed.
|
|
|
|
**`className? string`**
|
|
|
|
Defaults to an empty string. The classname will be set in the `<svg />` element.
|
|
|
|
**`width? number`**
|
|
|
|
Defaults to `400`. It will be set in the viewbox attr in the `<svg />`.
|
|
|
|
**`height? number`**
|
|
|
|
Defaults to `130`. It will be set in the viewbox attr in the `<svg />`.
|
|
|
|
**`gradientRatio? number`**
|
|
|
|
Defaults to `2`. Width of the animated gradient as a fraction of the viewbox width.
|
|
|
|
**`rtl? boolean`**
|
|
|
|
Defaults to `false`. Content right-to-left.
|
|
|
|
**`preserveAspectRatio?: string`**
|
|
|
|
Defaults to `xMidYMid meet`. Aspect ratio option of `<svg/>`. See the available options [here](https://github.com/danilowoz/react-content-loader/blob/master/src/interface.ts#L7).
|
|
|
|
**`primaryColor?: string`**
|
|
|
|
Defaults to `#f3f3f3` which is used as background of animation.
|
|
|
|
**`secondaryColor?: string`**
|
|
|
|
Defaults to `#ecebeb` which is used as the placeholder/layer of animation.
|
|
|
|
**`primaryOpacity?: string`**
|
|
|
|
Defaults to `1`. Background opacity (0 = transparent, 1 = opaque) used to solve a issue in [Safari](#safari--ios)
|
|
|
|
**`secondaryOpacity?: string`**
|
|
|
|
Defaults to `1`. Animation opacity (0 = transparent, 1 = opaque) used to solve a issue in [Safari](#safari--ios)
|
|
|
|
**`style?: React.CSSProperties`**
|
|
|
|
Defaults to an empty object.
|
|
|
|
**`uniquekey?: string`**
|
|
|
|
Defaults to random unique id. Use the same value of prop key, that will solve inconsistency on the SSR, see more [here](https://github.com/danilowoz/react-content-loader/issues/78).
|
|
|
|
## Examples
|
|
|
|
##### Facebook Style
|
|
|
|
```jsx
|
|
import { Facebook } from 'react-content-loader'
|
|
|
|
const MyFacebookLoader = () => <Facebook />
|
|
```
|
|
|
|
|
|
|
|
##### Instagram Style
|
|
|
|
```jsx
|
|
import { Instagram } from 'react-content-loader'
|
|
|
|
const MyInstagramLoader = () => <Instagram />
|
|
```
|
|
|
|
|
|
|
|
##### Code Style
|
|
|
|
```jsx
|
|
import { Code } from 'react-content-loader'
|
|
|
|
const MyCodeLoader = () => <Code />
|
|
```
|
|
|
|
|
|
|
|
##### List Style
|
|
|
|
```jsx
|
|
import { List } from 'react-content-loader'
|
|
|
|
const MyListLoader = () => <List />
|
|
```
|
|
|
|
|
|
|
|
##### Bullet list Style
|
|
|
|
```jsx
|
|
import { BulletList } from 'react-content-loader'
|
|
|
|
const MyBulletListLoader = () => <BulletList />
|
|
```
|
|
|
|
|
|
|
|
### Custom Style
|
|
|
|
For the custom mode, use the
|
|
[online tool](https://danilowoz.github.io/create-react-content-loader/).
|
|
|
|
```jsx
|
|
const MyLoader = () => (
|
|
<ContentLoader
|
|
height={140}
|
|
speed={1}
|
|
primaryColor={'#333'}
|
|
secondaryColor={'#999'}
|
|
>
|
|
{/* Only SVG shapes */}
|
|
<rect x="0" y="0" rx="5" ry="5" width="70" height="70" />
|
|
<rect x="80" y="17" rx="4" ry="4" width="300" height="13" />
|
|
<rect x="80" y="40" rx="3" ry="3" width="250" height="10" />
|
|
</ContentLoader>
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
|
|
|
|
## Similar packages
|
|
|
|
- [React Native](https://github.com/virusvn/react-native-svg-animated-linear-gradient);
|
|
- [Preact](https://github.com/bonitasoft/preact-content-loader);
|
|
- Vue.js: [vue-content-loading](https://github.com/LucasLeandro1204/vue-content-loading), [vue-content-loader](https://github.com/egoist/vue-content-loader);
|
|
- Angular: [ngx-content-loading](https://github.com/Gbuomprisco/ngx-content-loading), [ngx-content-loader](https://github.com/NetanelBasal/ngx-content-loader).
|
|
|
|
## Development
|
|
|
|
Fork the repo then clone it
|
|
|
|
`$ git clone git@github.com:YourUsername/react-content-loader.git && cd react-content-loader`
|
|
|
|
`$ yarn`: Install the dependencies;
|
|
|
|
`$ yarn build`: Build to production;
|
|
|
|
`$ yarn dev`: Run the docz to see your changes;
|
|
|
|
`$ yarn test`: Run all tests: type checking and unit tests;
|
|
|
|
`$ yarn test:watch`: Watch unit tests;
|
|
|
|
`$ yarn tsc`: Typescript checking;
|
|
|
|
`$ yarn tsc:watch`: Typescript checking with watching;
|
|
|
|
### Commit messages
|
|
|
|
Commit messages should follow the [commit message convention](https://conventionalcommits.org/) so, changelogs could be generated automatically by that. Commit messages are validated automatically upon commit. If you aren't familiar with the commit message convention, you can use yarn commit (or `npm run commit`) instead of git commit, which provides an interactive CLI for generating proper commit messages.
|
|
|
|
## License
|
|
|
|
[MIT](https://github.com/danilowoz/react-content-loader/blob/master/LICENSE)
|
|
|
|
## Known Issues
|
|
|
|
##### **Alpha is not working: Safari / iOS**
|
|
|
|
When using `rgba` as a `primaryColor` or `secondaryColor` value, [Safari does not respect the alpha channel](https://github.com/w3c/svgwg/issues/180), meaning that the color will be opaque. To prevent this, instead of using an `rgba` value for `primaryColor`/`secondaryColor`, use the `rgb` equivalent and move the alpha channel value to the `primaryOpacity`/`secondaryOpacity` props.
|
|
|
|
```jsx
|
|
{/* Opaque color in Safari and iOS */}
|
|
<ContentLoader
|
|
primaryColor="rgba(0,0,0,0.06)"
|
|
secondaryColor="rgba(0,0,0,0.12)">
|
|
|
|
```
|
|
|
|
```
|
|
{/_ Semi-transparent color in Safari and iOS _/}
|
|
<ContentLoader
|
|
primaryColor="rgb(0,0,0)"
|
|
secondaryColor="rgb(0,0,0)"
|
|
primaryOpacity={0.06}
|
|
secondaryOpacity={0.12}>
|
|
|
|
```
|
|
|
|
##### **Black box in Safari / iOS (again)**
|
|
|
|
Using base tag on a page that contains SVG elements fails to render and it looks like a black box. Just remove the **base-href** tag from the `<head />` and issue solved.
|
|
|
|
<img width="200" alt="Black box" src="https://user-images.githubusercontent.com/11562881/39406054-2f308de6-4bce-11e8-91fb-bbb35e29fc10.png" />
|
|
|
|
See: [#93](https://github.com/danilowoz/react-content-loader/issues/93) / [109](https://github.com/danilowoz/react-content-loader/issues/109)
|