danilowoz/react-content-loader
![danilowoz/react-content-loader](/images/project/repo-5_hub235ac8641791c90fc2cad85d50d87f4_43613_900x500_fit_q75_box.jpg)
SVG-Powered component to easily create placeholder loadings.
repo name | danilowoz/react-content-loader |
repo link | https://github.com/danilowoz/react-content-loader |
homepage | http://danilowoz.com/create-content-loader/ |
language | TypeScript |
size (curr.) | 4190 kB |
stars (curr.) | 8553 |
created | 2017-01-20 |
license | MIT License |
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;
- :pencil2: DIY: use the create-content-loader to create your own custom loaders easily;
- 📱 React Native support: same API, as same powerful features;
- ⚛️ Really lightweight: less than 2kB and 0 dependencies for web version;
Index
Getting Started
npm i react-content-loader --save
yarn add react-content-loader
For React Native
npm i react-content-loader react-native-svg --save
yarn add react-content-loader react-native-svg
CDN from JSDELIVR
Usage
There are two ways to use it:
1. Presets, see the examples:
import ContentLoader, { Facebook } from 'react-content-loader'
const MyLoader = () => <ContentLoader />
const MyFacebookLoader = () => <Facebook />
2. Custom mode, see the online tool
const MyLoader = () => (
<ContentLoader viewBox="0 0 380 70">
{/* 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
Or try the components editable demo hands-on and install it from bit.dev
Native
react-content-loader
can be used with React Native in the same way as web version with the same import:
1. Presets, see the examples:
import ContentLoader, { Facebook } from 'react-content-loader/native'
const MyLoader = () => <ContentLoader />
const MyFacebookLoader = () => <Facebook />
2. Custom mode
To create custom loaders there is an important difference: as React Native doesn’t have any native module for SVG components, it’s necessary to import the shapes from react-native-svg or use the named export Rect and Circle from react-content-loader
import:
import ContentLoader, { Rect, Circle } from 'react-content-loader/native'
const MyLoader = () => (
<ContentLoader viewBox="0 0 380 70">
<Circle cx="30" cy="30" r="30" />
<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>
)
Options
animate?: boolean
Defaults to true
. Opt-out of animations with false
title?: string
- Web only
Defaults to Loading interface...
. It’s used to describe what element it is. Use ‘'(empty string) to remove.
baseUrl?: string
- Web only
Required if you’re using <base url="/" />
document <head/>
.
Defaults to an empty string. This prop is common used as: <ContentLoader baseUrl={window.location.pathname} />
which will fill the SVG attribute with the relative path. Related #93.
speed?: number
Defaults to 1.2
. Animation speed in seconds.
interval?: number
- Web only
Defaults to 0.25
. Interval of time between runs of the animation, as a fraction of the animation speed.
viewBox?: string
Use viewBox props to set a custom viewBox value, for more information about how to use it, read the article How to Scale SVG.
gradientRatio?: number
- Web only
Defaults to 1.2
. Width of the animated gradient as a fraction of the viewbox width.
rtl?: boolean
Defaults to false
. Content right-to-left.
backgroundColor?: string
Defaults to #f5f6f7
which is used as background of animation.
foregroundColor?: string
Defaults to #eee
which is used as the foreground of animation.
backgroundOpacity?: number
- Web only
Defaults to 1
. Background opacity (0 = transparent, 1 = opaque) used to solve a issue in Safari
foregroundOpacity?: number
- Web only
Defaults to 1
. Animation opacity (0 = transparent, 1 = opaque) used to solve a issue in Safari
style?: React.CSSProperties
Defaults to an empty object.
uniqueKey?: string
- Web only
Defaults to random unique id. Use the same value of prop key, that will solve inconsistency on the SSR, see more here.
See all options live
Examples
Facebook Style
import { Facebook } from 'react-content-loader'
const MyFacebookLoader = () => <Facebook />
Instagram Style
import { Instagram } from 'react-content-loader'
const MyInstagramLoader = () => <Instagram />
Code Style
import { Code } from 'react-content-loader'
const MyCodeLoader = () => <Code />
List Style
import { List } from 'react-content-loader'
const MyListLoader = () => <List />
Bullet list Style
import { BulletList } from 'react-content-loader'
const MyBulletListLoader = () => <BulletList />
Custom Style
For the custom mode, use the online tool.
const MyLoader = () => (
<ContentLoader
height={140}
speed={1}
backgroundColor={'#333'}
foregroundColor={'#999'}
viewBox="0 0 380 70"
>
{/* 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: rn-placeholder, react-native-svg-animated-linear-gradient;
- Preact;
- Vue.js: vue-content-loading, vue-content-loader;
- Angular: ngx-content-loading, ngx-content-loader.
Development
Fork the repo then clone it
$ git clone git@github.com:YourUsername/react-content-loader.git && cd react-content-loader
$ npm i
: Install the dependencies;
$ npm run build
: Build to production;
$ npm run dev
: Run the docz to see your changes;
$ npm run test
: Run all tests: type checking, unit tests on web and native;
$ 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 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
Known Issues
Alpha is not working: Safari / iOS
When using rgba
as a backgroundColor
or foregroundColor
value, Safari does not respect the alpha channel, meaning that the color will be opaque. To prevent this, instead of using an rgba
value for backgroundColor
/foregroundColor
, use the rgb
equivalent and move the alpha channel value to the backgroundOpacity
/foregroundOpacity
props.
{/* Opaque color in Safari and iOS */}
<ContentLoader
backgroundColor="rgba(0,0,0,0.06)"
foregroundColor="rgba(0,0,0,0.12)">
{/_ Semi-transparent color in Safari and iOS _/}
<ContentLoader
backgroundColor="rgb(0,0,0)"
foregroundColor="rgb(0,0,0)"
backgroundOpacity={0.06}
foregroundOpacity={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.