Skip to content

Commit a214a24

Browse files
danilowozdanilowoz
authored
Improv/doc (#130)
* docs(Readme): Update tagline * docs(README): Usage * docs(README): Options * docs(README): Development * docs(README): Known issues Closes #93 * docs(README): Some fixes
1 parent bfd2707 commit a214a24

File tree

2 files changed

+484
-129
lines changed

2 files changed

+484
-129
lines changed

‎README.md‎

Lines changed: 142 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -6,195 +6,252 @@
66
<img width="400" alt="Example's react-content-loader" src="https://user-images.githubusercontent.com/4838076/34308760-ec55df82-e735-11e7-843b-2e311fa7b7d0.gif" />
77
</p>
88

9-
React component that uses SVG to create a collection of loaders which simulates the structure of the
10-
content that will be loaded, similar to Facebook cards loaders.
11-
12-
[![Size](https://img.shields.io/badge/gzip%20size-1.4kb-brightgreen.svg)]()
13-
[![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()
14-
[![CircleCI](https://img.shields.io/circleci/project/github/RedSparr0w/node-csgo-parser.svg)]()
15-
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)]()
16-
[![](https://data.jsdelivr.com/v1/package/npm/react-content-loader/badge)](https://www.jsdelivr.com/package/npm/react-content-loader)
9+
SVG-Powered component to easily create placeholder loadings (like Facebook's cards loading).
1710

1811
## Features
1912

20-
* :gear: **Completely customizable:** you can change the colors, speed, sizes and even with RTL content support;
21-
* :pencil2: **Create your own loading:** use the
22-
[create-content-loader](https://danilowoz.github.io/create-content-loader/) to create
23-
your own custom loadings easily;
24-
* :ok_hand: **You can use right now:** there are a lot of presets to use it, see the
25-
[examples](#examples);
26-
* :rocket: **Performance:** written using only the SVG API.
13+
- :gear: **Customizable:** Feel free to change the colors, speed, sizes and even **RTL**;
14+
- :ok_hand: **Plug and play:** with many presets to use, see the [examples](#examples);
15+
- :pencil2: **DIY:** use the [create-content-loader](https://danilowoz.github.io/create-content-loader/) to create your own custom loaders easily;
16+
- ⚛️ **Lightweight:** only **1.4kB** gzipped and **0 dependencies**;
2717

28-
## Usage
18+
## Index
19+
20+
- [Getting Started](#getting-started)
21+
- [Usage](#usage)
22+
- [Options](#options)
23+
- [Examples](#examples)
24+
- [Similar packages](#similars-packages)
25+
- [Development](#development)
26+
- [Known Issues](#known-issues)
27+
28+
## Getting Started
2929

30-
### Installation
30+
```sh
31+
npm i react-content-loader --save
32+
```
33+
34+
```sh
35+
yarn add react-content-loader
36+
```
3137

32-
Yarn: `$ yarn add react-content-loader`
38+
CDN from [JSDELIVR](https://www.jsdelivr.com/package/npm/react-content-loader)
3339

34-
Npm: `$ npm i react-content-loader --save`
40+
## Usage
3541

36-
CDN: [from JSDELIVR](https://www.jsdelivr.com/package/npm/react-content-loader)
42+
There are two ways to use it:
3743

38-
**You can use it in two ways ([See the options)](#options):**
44+
**1. Presets, see the [examples](#examples):**
3945

4046
```jsx
41-
// import the component
4247
import ContentLoader, { Facebook } from 'react-content-loader'
4348

4449
const MyLoader = () => <ContentLoader />
4550
const MyFacebookLoader = () => <Facebook />
4651
```
4752

48-
**Or in custom mode, using the
49-
[online tool](https://danilowoz.github.io/create-react-content-loader/)**
53+
**2. Custom mode, see the [online tool](https://danilowoz.github.io/create-react-content-loader/)**
5054

5155
```jsx
5256
const MyLoader = () => (
5357
<ContentLoader>
54-
{/* Pure SVG */}
58+
{/* Only SVG shapes */}
5559
<rect x="0" y="0" rx="5" ry="5" width="70" height="70" />
5660
<rect x="80" y="17" rx="4" ry="4" width="300" height="13" />
5761
<rect x="80" y="40" rx="3" ry="3" width="250" height="10" />
5862
</ContentLoader>
5963
)
6064
```
6165

66+
**Still not clear?** Take a look at this working example at [codesandbox.io](https://codesandbox.io/s/moojk887z9)
67+
6268
## Options
6369

64-
| Name | Type | Default | Description |
65-
| ----------------------- | ----------- | ---------------------- | ------------------------------------------------------------------------- |
66-
| **animate** | `{Boolean}` | `true` | `false` to render with no animation |
67-
| **ariaLabel** | `{String}` | `Loading interface...` | Describe what element it is |
68-
| **speed** | `{Number}` | `2` | Animation speed in seconds |
69-
| **className** | `{String}` | `''` | Classname in the `<svg/>` |
70-
| **width** | `{Number}` | `400` | viewBox width of `<svg/>` |
71-
| **height** | `{Number}` | `130` | viewBox height of `<svg/>` |
72-
| **rtl** | `{Boolean}` | `false` | Right-to-left animation |
73-
| **preserveAspectRatio** | `{String}` | `xMidYMid meet` | Aspect ratio option of `<svg/>` |
74-
| **primaryColor** | `{String}` | `#f3f3f3` | Background |
75-
| **secondaryColor** | `{String}` | `#ecebeb` | Animation color |
76-
| **primaryOpacity** | `{Number}` | `1` | Background opacity (0 = transparent, 1 = opaque) |
77-
| **secondaryOpacity** | `{Number}` | `1` | Animation opacity (0 = transparent, 1 = opaque) |
78-
| **style** | `{Object}` | `null` | Ex: `{ width: '100%', height: '70px' }` |
79-
| **uniquekey** | `{String}` | random unique id | Use the same value of prop key, that will solve inconsistency on the SSR. |
80-
81-
### Examples
82-
83-
#### Facebook Style
70+
**`animate?: boolean`**
71+
72+
Defaults to `true`. Opt-out of animations with `false`
73+
74+
**`ariaLabel? string | boolean`**
75+
76+
Defaults to `Loading interface...`. It's used to describe what element it is. Use `false` to remove.
77+
78+
**`speed?: number`**
79+
80+
Defaults to `2`. Animation speed in seconds.
81+
82+
**`className? string`**
83+
84+
Defaults to an empty string. The classname will be set in the `<svg />` element.
85+
86+
**`width? number`**
87+
88+
Defaults to `400`. It will be set in the viewbox attr in the `<svg />`.
89+
90+
**`height? number`**
91+
92+
Defaults to `130`. It will be set in the viewbox attr in the `<svg />`.
93+
94+
**`rtl? boolean`**
95+
96+
Defaults to `false`. Content right-to-left.
97+
98+
**`preserveAspectRatio?: string`**
99+
100+
Defaults to `xMidYMid meet`. Aspect ratio option of `<svg/>`. See the available options [here](https://github.com/danilowoz/react-content-loader/blob/improv/doc/src/interface.ts#L7).
101+
102+
**`primaryColor?: string`**
103+
104+
Defaults to `#f3f3f3` which is used as background of animation.
105+
106+
**`secondaryColor?: string`**
107+
108+
Defaults to `#ecebeb` which is used as the placeholder/layer of animation.
109+
110+
**`primaryOpacity?: string`**
111+
112+
Defaults to `1`. Background opacity (0 = transparent, 1 = opaque) used to solve a issue in [Safari](#safari--ios)
113+
114+
**`secondaryOpacity?: string`**
115+
116+
Defaults to `1`. Animation opacity (0 = transparent, 1 = opaque) used to solve a issue in [Safari](#safari--ios)
117+
118+
**`style?: React.CSSProperties`**
119+
120+
Defaults to an empty object.
121+
122+
**`uniquekey?: string`**
123+
124+
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).
125+
126+
## Examples
127+
128+
##### Facebook Style
84129

85130
```jsx
86-
// import the component
87131
import { Facebook } from 'react-content-loader'
88132

89133
const MyFacebookLoader = () => <Facebook />
90134
```
91135

92136
![Facebook Style](https://user-images.githubusercontent.com/4838076/34308760-ec55df82-e735-11e7-843b-2e311fa7b7d0.gif)
93137

94-
#### Instagram Style
138+
##### Instagram Style
95139

96140
```jsx
97-
// import the component
98141
import { Instagram } from 'react-content-loader'
99142

100143
const MyInstagramLoader = () => <Instagram />
101144
```
102145

103146
![Instagram Style](https://cloud.githubusercontent.com/assets/4838076/22555637/749f9e26-e94b-11e6-84ff-83cd415c1eb9.gif)
104147

105-
#### Code Style
148+
##### Code Style
106149

107150
```jsx
108-
// import the component
109151
import { Code } from 'react-content-loader'
110152

111153
const MyCodeLoader = () => <Code />
112154
```
113155

114156
![Code Style](https://cloud.githubusercontent.com/assets/4838076/22555473/effa54c2-e94a-11e6-9128-9b608bcc69d9.gif)
115157

116-
#### List Style
158+
##### List Style
117159

118160
```jsx
119-
// import the component
120161
import { List } from 'react-content-loader'
121162

122163
const MyListLoader = () => <List />
123164
```
124165

125166
![List Style](https://user-images.githubusercontent.com/4838076/36352948-b8931430-149e-11e8-9f4b-3f00bc444a6d.gif)
126167

127-
#### Bullet list Style
168+
##### Bullet list Style
128169

129170
```jsx
130-
// import the component
131171
import { BulletList } from 'react-content-loader'
132172

133173
const MyBulletListLoader = () => <BulletList />
134174
```
135175

136176
![Bullet list Style](https://user-images.githubusercontent.com/4838076/31998372-59817bac-b96e-11e7-8ef8-07f61670ee18.gif)
137177

138-
#### Custom Style
178+
### Custom Style
139179

140-
**For the custom mode, use the
141-
[online tool](https://danilowoz.github.io/create-react-content-loader/)**
180+
For the custom mode, use the
181+
[online tool](https://danilowoz.github.io/create-react-content-loader/).
142182

143183
```jsx
144184
const MyLoader = () => (
145-
<ContentLoader height={140} speed={1} primaryColor={'#333'} secondaryColor={'#999'}>
146-
{/* Pure SVG */}
185+
<ContentLoader
186+
height={140}
187+
speed={1}
188+
primaryColor={'#333'}
189+
secondaryColor={'#999'}
190+
>
191+
{/* Only SVG shapes */}
147192
<rect x="0" y="0" rx="5" ry="5" width="70" height="70" />
148193
<rect x="80" y="17" rx="4" ry="4" width="300" height="13" />
149194
<rect x="80" y="40" rx="3" ry="3" width="250" height="10" />
150195
</ContentLoader>
151196
)
152197
```
153198

199+
---
200+
154201
![Custom](https://user-images.githubusercontent.com/4838076/36352947-b87019a8-149e-11e8-99ba-c71c2bcf8733.gif)
155202

156-
## Similars
203+
## Similar packages
157204

158-
* [React Native](https://github.com/virusvn/react-native-svg-animated-linear-gradient);
159-
* [Preact](https://github.com/bonitasoft/preact-content-loader);
160-
* Vue.js: [vue-content-loading](https://github.com/LucasLeandro1204/vue-content-loading), [vue-content-loader](https://github.com/egoist/vue-content-loader);
161-
* [Angular](https://github.com/Gbuomprisco/ngx-content-loading).
205+
- [React Native](https://github.com/virusvn/react-native-svg-animated-linear-gradient);
206+
- [Preact](https://github.com/bonitasoft/preact-content-loader);
207+
- Vue.js: [vue-content-loading](https://github.com/LucasLeandro1204/vue-content-loading), [vue-content-loader](https://github.com/egoist/vue-content-loader);
208+
- [Angular](https://github.com/Gbuomprisco/ngx-content-loading).
162209

163210
## Development
164211

165212
Fork the repo then clone it
166213

167214
`$ git clone [email protected]:YourUsername/react-content-loader.git && cd react-content-loader`
215+
`$ yarn`: Install the dependencies;
216+
`$ yarn build`: Build to production;
217+
`$ yarn dev`: Run the docz to see your changes;
218+
`$ yarn test`: Run all tests: type checking and unit tests;
219+
`$ yarn test:watch`: Watch unit tests;
220+
`$ yarn tsc`: Typescript checking;
221+
`$ yarn tsc:watch`: Typescript checking with watching;
168222

169-
Install the dependencies
223+
## License
170224

171-
`$ yarn`
225+
[MIT](https://github.com/danilowoz/react-content-loader/blob/master/LICENSE)
172226

173-
Run the docz to see your changes
227+
## Known Issues
174228

175-
`$ yarn dev`
229+
##### **Alpha is not working: Safari / iOS**
176230

177-
## License
231+
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.
178232

179-
[MIT](https://github.com/danilowoz/react-content-loader/blob/master/LICENSE)
233+
```jsx
234+
{/* Opaque color in Safari and iOS */}
235+
<ContentLoader
236+
primaryColor="rgba(0,0,0,0.06)"
237+
secondaryColor="rgba(0,0,0,0.12)">
180238

181-
## Known Issues
239+
```
182240

183-
* **Safari / iOS**
184-
185-
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.
186-
187-
```jsx
188-
{/* Opaque color in Safari and iOS */}
189-
<ContentLoader
190-
primaryColor="rgba(0,0,0,0.06)"
191-
secondaryColor="rgba(0,0,0,0.12)">
192-
193-
194-
{/* Semi-transparent color in Safari and iOS */}
195-
<ContentLoader
241+
```
242+
{/_ Semi-transparent color in Safari and iOS _/}
243+
<ContentLoader
196244
primaryColor="rgb(0,0,0)"
197245
secondaryColor="rgb(0,0,0)"
198246
primaryOpacity={0.06}
199247
secondaryOpacity={0.12}>
200-
```
248+
249+
```
250+
251+
##### **Black box in Safari / iOS (again)**
252+
253+
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.
254+
255+
<img width="200" alt="Black box" src="https://user-images.githubusercontent.com/11562881/39406054-2f308de6-4bce-11e8-91fb-bbb35e29fc10.png" />
256+
257+
See: [#93](https://github.com/danilowoz/react-content-loader/issues/93) / [109](https://github.com/danilowoz/react-content-loader/issues/109)

0 commit comments

Comments
 (0)