From 02e98eb0b160a39754d071343456399782182f05 Mon Sep 17 00:00:00 2001 From: Danilo Woznica Date: Sun, 5 Apr 2020 13:37:40 +0100 Subject: [PATCH] Docs/troubleshooting (#191) * docs(readme): adds troubleshooting section * docs(readme): reorder sections --- README.md | 90 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 50 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 8a15d160..e94a7130 100755 --- a/README.md +++ b/README.md @@ -1,6 +1,3 @@ -

- react-europe-badge -

react-content-loader

@@ -25,9 +22,9 @@ SVG-Powered component to easily create placeholder loadings (like Facebo - [Native](#native) - [Options](#options) - [Examples](#examples) +- [Troubleshooting](#troubleshooting) - [Similar packages](#similarpackages) - [Development](#development) -- [Known Issues](#knownissues) ## Getting Started @@ -138,7 +135,7 @@ Use viewBox props to set a custom viewBox value, for more information about how #### **`gradientRatio?: number`** - _Web only_ -Defaults to `1.2`. Width of the animated gradient as a fraction of the viewbox width. +Defaults to `1.2`. Width of the animated gradient as a fraction of the view box width. #### **`rtl?: boolean`** @@ -154,11 +151,11 @@ 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](#safari--ios) +Defaults to `1`. Background opacity (0 = transparent, 1 = opaque) used to solve an issue in [Safari](#safari--ios) #### **`foregroundOpacity?: number`** - _Web only_ -Defaults to `1`. Animation opacity (0 = transparent, 1 = opaque) used to solve a issue in [Safari](#safari--ios) +Defaults to `1`. Animation opacity (0 = transparent, 1 = opaque) used to solve an issue in [Safari](#safari--ios) #### **`style?: React.CSSProperties`** @@ -244,10 +241,52 @@ const MyLoader = () => ( ) ``` ---- - ![Custom](https://user-images.githubusercontent.com/4838076/36352947-b87019a8-149e-11e8-99ba-c71c2bcf8733.gif) +## Troubleshooting + +#### Server-side rendering (SSR) - Match snapshot + +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. + +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: + +```jsx +import { Facebook } from 'react-content-loader' + +const MyFacebookLoader = () => +``` + + +#### **Alpha is not working: Safari / iOS** + +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. + +```jsx +{/* Opaque color in Safari and iOS */} + + + +{/_ Semi-transparent color in Safari and iOS _/} + + + +``` + +#### **Black box in Safari / iOS (again)** + +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 `` and issue solved. + +black box + +See: [#93](https://github.com/danilowoz/react-content-loader/issues/93) / [109](https://github.com/danilowoz/react-content-loader/issues/109) + ## Similar packages - 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); @@ -255,6 +294,8 @@ const MyLoader = () => ( - 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 @@ -284,34 +325,3 @@ Commit messages should follow the [commit message convention](https://con ## 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 `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. - -```jsx -{/* Opaque color in Safari and iOS */} - - - -{/_ Semi-transparent color in Safari and iOS _/} - - - -``` - -##### **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 `` and issue solved. - -![](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)