Skip to content

docs: correct web API descriptions and examples #342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dajiaohuang wants to merge 1 commit into
base: master
Choose a base branch
from
+26 −48
Open

docs: correct web API descriptions and examples #342

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,17 +112,17 @@ const MyLoader = () => (
| ---------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`animate?: boolean`** <br/> Defaults to `true` | React DOM<br/>React Native | Opt-out of animations with `false` |
| **`title?: string`** <br/> Defaults to `Loading...` | React DOM only | It's used to describe what element it is. <br />Use `''` (empty string) to remove. |
| **`baseUrl?: string`**<br /> Defaults to an empty string | React DOM only | Required if you're using `<base url="/" />` document `<head/>`. <br/>This prop is common used as: <br/>`<ContentLoader baseUrl={window.location.pathname} />` which will fill the SVG attribute with the relative path. Related [#93](https://github.com/danilowoz/react-content-loader/issues/93). |
| **`baseUrl?: string`**<br /> Defaults to an empty string | React DOM only | Required if you're using `<base href="/" />` document `<head/>`. <br/>This prop is common used as: <br/>`<ContentLoader baseUrl={window.location.pathname} />` which will fill the SVG attribute with the relative path. Related [#93](https://github.com/danilowoz/react-content-loader/issues/93). |
| **`speed?: number`** <br /> Defaults to `1.2` | React DOM<br/>React Native | Animation speed in seconds. |
| **`viewBox?: string`** <br /> Defaults to `undefined` | React DOM<br/>React Native | Use viewBox props to set a custom viewBox value, <br/>for more information about how to use it, <br/>read the article [How to Scale SVG](https://css-tricks.com/scale-svg/). |
| **`gradientRatio?: number`** <br /> Defaults to `1.2` | React DOM only | Width of the animated gradient as a fraction of the view box width. |
| **`gradientRatio?: number`** <br /> Defaults to `2` | React DOM only | Width of the animated gradient as a fraction of the view box width. |
| **`rtl?: boolean`** <br /> Defaults to `false` | React DOM<br/>React Native | Content right-to-left. |
| **`backgroundColor?: string`** <br /> Defaults to `#f5f6f7` | React DOM<br/>React Native | Used as background of animation. |
| **`foregroundColor?: string`** <br /> Defaults to `#eee` | React DOM<br/>React Native | Used as the foreground of animation. |
| **`backgroundOpacity?: number`** <br /> Defaults to `1` | React DOM<br/>React Native | Background opacity (0 = transparent, 1 = opaque)<br/>used to solve an issue in [Safari](#safari--ios) |
| **`foregroundOpacity?: number`** <br /> Defaults to `1` | React DOM<br/>React Native | Animation opacity (0 = transparent, 1 = opaque)<br/>used to solve an issue in [Safari](#safari--ios) |
| **`style?: React.CSSProperties`** <br /> Defaults to `{}` | React DOM only | |
| **`uniqueKey?: string`** <br /> Defaults to random unique id | React DOM only | Use the same value of prop key, <br/>that will solve inconsistency on the SSR, see more [here](https://github.com/danilowoz/react-content-loader/issues/78). |
| **`uniqueKey?: string`** <br /> Defaults to a React.useId-generated id | React DOM only | Override the generated SVG ids with a value unique to each loader. Useful for stable snapshot tests; see [SSR and snapshots](#server-side-rendering-ssr---match-snapshot). |
| **`beforeMask?: JSX.Element`** <br /> Defaults to null | React DOM<br/>React Native | Define custom shapes before content, <br/>see more [here](https://github.com/danilowoz/react-content-loader/issues/266). |

See all options [live](https://danilowoz.com/react-content-loader/)
Expand Down Expand Up @@ -224,9 +224,9 @@ const MyCodeLoader = () => (

#### 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.
The web component uses `React.useId` to connect each SVG's clip path, gradient and title. These ids match between the server and client when the rendered component tree is the same.

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:
For stable ids in snapshot tests, you can override the generated id with `uniqueKey`. Give each loader a distinct value, and use the same value on the server and client:

```jsx
import { Facebook } from 'react-content-loader'
Expand All @@ -239,20 +239,21 @@ const MyFacebookLoader = () => <Facebook uniqueKey="my-random-value" />
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 */}
<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}>

<>
{/* 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)**
Expand Down
37 changes: 7 additions & 30 deletions docs/index.stories.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ foregroundColor.story = {
export const backgroundOpacity = () => {
return (
<>
<SyntaxCode>{'<ContentLoader backgroundOpacity="#333" />'}</SyntaxCode>
<SyntaxCode>{'<ContentLoader backgroundOpacity={0.06} />'}</SyntaxCode>
<ContentLoader backgroundOpacity={0.06} />
</>
)
Expand Down Expand Up @@ -141,7 +141,7 @@ baseURL.story = {
parameters: {
notes: `## \`baseUrl?: string\`

Required if you're using \`<base url="/" />\` in the \`<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](https://github.com/danilowoz/react-content-loader/issues/93).
Required if you're using \`<base href="/" />\` in the \`<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](https://github.com/danilowoz/react-content-loader/issues/93).
`,
},
}
Expand Down Expand Up @@ -212,29 +212,6 @@ gradientRatio.story = {
},
}

/**
* Gradient Direction
*/
export const gradientDirection = () => {
return (
<>
<SyntaxCode>{`<BulletList gradientDirection="left-right" />`}</SyntaxCode>
<BulletList gradientDirection="left-right" />

<SyntaxCode>{`<BulletList gradientDirection="top-bottom" />`}</SyntaxCode>
<BulletList gradientDirection="top-bottom" />
</>
)
}

gradientDirection.story = {
parameters: {
notes: `## \`gradientDirection?: 'left-right' | 'top-bottom' \`

Defaults to \`left-right\`. Direction in which the gradient is animated. Useful to implement top-down animations`,
},
}

/**
* Speed
*/
Expand Down Expand Up @@ -293,7 +270,7 @@ uniqueKey.story = {
parameters: {
notes: `## \`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).`,
Defaults to an id generated by React.useId. Set a unique value to override the generated SVG ids, for example in snapshot tests.`,
},
}

Expand All @@ -303,8 +280,8 @@ uniqueKey.story = {
export const responsive = () => {
return (
<div style={{ width: 200, border: '1px solid #eee' }}>
<SyntaxCode>{"<ContentLoader style={{ width: '100%' }} />'"}</SyntaxCode>
<ContentLoader />
<SyntaxCode>{"<ContentLoader style={{ width: '100%' }} />"}</SyntaxCode>
<ContentLoader style={{ width: '100%' }} />
</div>
)
}
Expand All @@ -323,9 +300,9 @@ export const title = () => {

title.story = {
parameters: {
notes: `## \`title?: string | boolean\`
notes: `## \`title?: string\`

Defaults to \`Loading interface...\`. It's used to describe what element it is. Use \`false\` to remove.
Defaults to \`Loading...\`. It's used to describe what element it is. Use \`''\` (empty string) to remove.
`,
},
}
Expand Down