Skip to content

Commit 02e98eb

Browse files
danilowozdanilowoz
authored
Docs/troubleshooting (#191)
* docs(readme): adds troubleshooting section * docs(readme): reorder sections
1 parent 70e3d5d commit 02e98eb

File tree

1 file changed

+50
-40
lines changed

1 file changed

+50
-40
lines changed

‎README.md‎

Lines changed: 50 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
<p align="center">
2-
<a href="https://www.react-europe.org/"><img alt="react-europe-badge" src="https://img.shields.io/badge/join%20us%20at-ReactEurope-blue"/></a>
3-
</p>
41
<p align="center">
52
<img width="350" alt="react-content-loader" src="https://user-images.githubusercontent.com/4838076/34419335-5669c3f8-ebea-11e7-9668-c47b7846970b.png"/>
63
</p>
@@ -25,9 +22,9 @@ SVG-Powered component to easily create placeholder loadings (like Facebo
2522
- [Native](#native)
2623
- [Options](#options)
2724
- [Examples](#examples)
25+
- [Troubleshooting](#troubleshooting)
2826
- [Similar packages](#similarpackages)
2927
- [Development](#development)
30-
- [Known Issues](#knownissues)
3128

3229
## Getting Started
3330

@@ -138,7 +135,7 @@ Use viewBox props to set a custom viewBox value, for more information about how
138135

139136
#### **`gradientRatio?: number`** - _Web only_
140137

141-
Defaults to `1.2`. Width of the animated gradient as a fraction of the viewbox width.
138+
Defaults to `1.2`. Width of the animated gradient as a fraction of the view box width.
142139

143140
#### **`rtl?: boolean`**
144141

@@ -154,11 +151,11 @@ Defaults to `#eee` which is used as the foreground of animation.
154151

155152
#### **`backgroundOpacity?: number`** - _Web only_
156153

157-
Defaults to `1`. Background opacity (0 = transparent, 1 = opaque) used to solve a issue in [Safari](#safari--ios)
154+
Defaults to `1`. Background opacity (0 = transparent, 1 = opaque) used to solve an issue in [Safari](#safari--ios)
158155

159156
#### **`foregroundOpacity?: number`** - _Web only_
160157

161-
Defaults to `1`. Animation opacity (0 = transparent, 1 = opaque) used to solve a issue in [Safari](#safari--ios)
158+
Defaults to `1`. Animation opacity (0 = transparent, 1 = opaque) used to solve an issue in [Safari](#safari--ios)
162159

163160
#### **`style?: React.CSSProperties`**
164161

@@ -244,17 +241,61 @@ const MyLoader = () => (
244241
)
245242
```
246243

247-
---
248-
249244
![Custom](https://user-images.githubusercontent.com/4838076/36352947-b87019a8-149e-11e8-99ba-c71c2bcf8733.gif)
250245

246+
## Troubleshooting
247+
248+
#### Server-side rendering (SSR) - Match snapshot
249+
250+
As the main component generates random values to match the id of the SVG element with background style, it can encounter unexpected errors and unmatching warning on render, once the random value of id will be generated twice, in case of SSR: server and client; or in case of snapshot test: on the first match and re-running the test.
251+
252+
To fix it, set the prop [`uniqueKey`](https://github.com/danilowoz/react-content-loader#uniquekey-string---web-only), then the id will not be random anymore:
253+
254+
```jsx
255+
import { Facebook } from 'react-content-loader'
256+
257+
const MyFacebookLoader = () => <Facebook uniqueKey="my-random-valye" />
258+
```
259+
260+
261+
#### **Alpha is not working: Safari / iOS**
262+
263+
When using `rgba` as a `backgroundColor` or `foregroundColor` 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 a `rgba` value for `backgroundColor`/`foregroundColor`, use the `rgb` equivalent and move the alpha channel value to the `backgroundOpacity`/`foregroundOpacity` props.
264+
265+
```jsx
266+
{/* Opaque color in Safari and iOS */}
267+
<ContentLoader
268+
  backgroundColor="rgba(0,0,0,0.06)"
269+
  foregroundColor="rgba(0,0,0,0.12)">
270+
271+
272+
{/_ Semi-transparent color in Safari and iOS _/}
273+
<ContentLoader
274+
    backgroundColor="rgb(0,0,0)"
275+
    foregroundColor="rgb(0,0,0)"
276+
    backgroundOpacity={0.06}
277+
    foregroundOpacity={0.12}>
278+
279+
280+
```
281+
282+
#### **Black box in Safari / iOS (again)**
283+
284+
Using the 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.
285+
286+
<img width="350" src="https://user-images.githubusercontent.com/11562881/39406054-2f308de6-4bce-11e8-91fb-bbb35e29fc10.png" alt="black box" />
287+
288+
See: [#93](https://github.com/danilowoz/react-content-loader/issues/93) / [109](https://github.com/danilowoz/react-content-loader/issues/109)
289+
251290
## Similar packages
252291

253292
- React Native: [rn-placeholder](https://github.com/mfrachet/rn-placeholder), [react-native-svg-animated-linear-gradient](https://github.com/virusvn/react-native-svg-animated-linear-gradient);
254293
- [Preact](https://github.com/bonitasoft/preact-content-loader);
255294
- Vue.js: [vue-content-loading](https://github.com/LucasLeandro1204/vue-content-loading), [vue-content-loader](https://github.com/egoist/vue-content-loader);
256295
- Angular: [ngx-content-loading](https://github.com/Gbuomprisco/ngx-content-loading), [ngx-content-loader](https://github.com/NetanelBasal/ngx-content-loader).
257296

297+
----
298+
258299
## Development
259300

260301
Fork the repo then clone it
@@ -284,34 +325,3 @@ Commit messages should follow the [commit message convention](https://con
284325
## License
285326

286327
[MIT](https://github.com/danilowoz/react-content-loader/blob/master/LICENSE)
287-
288-
## Known Issues
289-
290-
##### **Alpha is not working: Safari / iOS**
291-
292-
When using `rgba` as a `backgroundColor` or `foregroundColor` 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 `backgroundColor`/`foregroundColor`, use the `rgb` equivalent and move the alpha channel value to the `backgroundOpacity`/`foregroundOpacity` props.
293-
294-
```jsx
295-
{/* Opaque color in Safari and iOS */}
296-
<ContentLoader
297-
  backgroundColor="rgba(0,0,0,0.06)"
298-
  foregroundColor="rgba(0,0,0,0.12)">
299-
300-
301-
{/_ Semi-transparent color in Safari and iOS _/}
302-
<ContentLoader
303-
    backgroundColor="rgb(0,0,0)"
304-
    foregroundColor="rgb(0,0,0)"
305-
    backgroundOpacity={0.06}
306-
    foregroundOpacity={0.12}>
307-
308-
309-
```
310-
311-
##### **Black box in Safari / iOS (again)**
312-
313-
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.
314-
315-
![](https://user-images.githubusercontent.com/11562881/39406054-2f308de6-4bce-11e8-91fb-bbb35e29fc10.png)
316-
317-
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)