Skip to content

Commit df4f4b3

Browse files
jscottsmithjscottsmith
committed
docs: update readme and add demos
1 parent a3da5d2 commit df4f4b3

File tree

2 files changed

+26
-104
lines changed

2 files changed

+26
-104
lines changed

‎README.md

Lines changed: 20 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -3,132 +3,48 @@
33
[![NPM Version Latest](https://img.shields.io/npm/v/react-scroll-parallax/latest)](https://www.npmjs.com/package/react-scroll-parallax)
44
[![NPM Version Beta](https://img.shields.io/npm/v/react-scroll-parallax/beta)](https://www.npmjs.com/package/react-scroll-parallax)
55
[![NPM Downloads](https://img.shields.io/npm/dm/react-scroll-parallax)](https://www.npmjs.com/package/react-scroll-parallax)
6-
[![Codecov](https://codecov.io/gh/jscottsmith/react-scroll-parallax/branch/master/graph/badge.svg)](https://codecov.io/gh/jscottsmith/react-scroll-parallax)
6+
[![Codecov](https://codecov.io/gh/jscottsmith/react-scroll-parallax/branch/v3/graph/badge.svg)](https://codecov.io/gh/jscottsmith/react-scroll-parallax)
77

88
[![Test and Lint](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/main.yml/badge.svg)](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/main.yml)
99
[![Storybook](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/surge.yml/badge.svg)](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/surge.yml)
10-
[![Coverage](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/coverage.yml/badge.svg)](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/coverage.yml)
10+
[![Storybook](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/coverage.yml/badge.svg)](https://github.com/jscottsmith/react-scroll-parallax/actions/workflows/coverage.yml)
1111

12-
React hooks and components to create parallax scroll effects for banners, images or any other DOM elements. Utilizes [Parallax Controller](https://github.com/jscottsmith/parallax-controller) to add vertical or horizontal scrolling based effects to elements. [Optimized](https://parallax-controller.vercel.app/docs/performance) to _reduce_ jank on scroll and works with SSR and SSG rendered React apps.
12+
React hooks and components to create parallax scroll effects for banners, images or any other DOM elements. Utilizes [Parallax Controller](https://parallax-controller.v1.damnthat.tv) to add vertical or horizontal scrolling based effects to elements. [Optimized](https://parallax-controller.v1.damnthat.tv/docs/performance) to _reduce_ jank on scroll and works with SSR and SSG rendered React apps.
1313

14-
If you're coming from [V2](https://github.com/jscottsmith/react-scroll-parallax/tree/v2.4.2), here's a [migration guide](https://github.com/jscottsmith/react-scroll-parallax/blob/master/docs/migration-guide.md).
14+
If you're coming from [V2](https://github.com/jscottsmith/react-scroll-parallax/tree/v2.4.2), here's a [migration guide](https://react-scroll-parallax.v3.damnthat.tv/docs/migration-guides/v2-migration-guide).
1515

16-
## Examples
17-
18-
#### V3 Storybook
19-
20-
See the [Storybook](https://react-scroll-parallax-v3.surge.sh) for example usage of each component
21-
22-
- [Storybook](https://react-scroll-parallax-v3.surge.sh) - [Source](/stories)
23-
24-
#### Demos
25-
26-
Some demo websites using Parallax components
27-
28-
- [Demo 1](https://jscottsmith.github.io/react-scroll-parallax-examples/examples/parallax-example/) - [Source](https://github.com/jscottsmith/react-scroll-parallax-examples)
29-
- [Demo 2](https://react-scroll-parallax.netlify.com/) - [Source](https://github.com/jscottsmith/react-parallax-site)
30-
31-
## Install
16+
## Install (v3 beta)
3217

3318
With npm
3419

3520
```
36-
npm install react-scroll-parallax
21+
npm install react-scroll-parallax@beta
3722
```
3823

3924
or yarn
4025

4126
```
42-
yarn add react-scroll-parallax
27+
yarn add react-scroll-parallax@beta
4328
```
4429

45-
## Documentation
30+
## Getting Started
4631

47-
- [Example Usage](#usage)
48-
- [Optimizations to Reduce Jank](#optimizations-to-reduce-jank)
32+
- [Usage](https://react-scroll-parallax.v3.damnthat.tv/docs/usage/)
33+
- [How it works](https://react-scroll-parallax.v3.damnthat.tv/docs/examples/how-it-works)
4934

50-
### Docs: Components
35+
### Demos
5136

52-
- [`<Parallax>`](/docs/parallax-component.md)
53-
- [`<ParallaxBanner>`](/docs/parallax-banner-component.md)
54-
- [`<ParallaxProvider>`](/docs/parallax-provider-component.md)
37+
- [Storybook v3](https://react-scroll-parallax-v3.surge.sh/) - [Source Code](https://github.com/jscottsmith/react-scroll-parallax/tree/v3/stories)
38+
- [Demo 1](https://jscottsmith.github.io/react-scroll-parallax-examples/examples/parallax-example/) - [Source Code (old 1.x version)](https://github.com/jscottsmith/react-scroll-parallax-examples)
39+
- [Demo 2](https://react-scroll-parallax.netlify.app/) - [Source Code (old 2.x version)](https://github.com/jscottsmith/react-parallax-site)
5540

5641
### Docs: Hooks
5742

58-
- [`useParallax()`](/docs/use-parallax-hook.md)
59-
- [`useController()`](/#todo)
60-
- [`useParallaxImage`](/#todo)
61-
62-
## Usage
63-
64-
### First: Wrap with a ParallaxProvider
65-
66-
The [`<ParallaxProvider>`](#parallaxprovider) must wrap the component tree that contains all `<Parallax>` components. This should be a top level component like `<App>`. For example:
67-
68-
```jsx
69-
import { ParallaxProvider } from 'react-scroll-parallax';
70-
71-
function App() {
72-
render() {
73-
return (
74-
<ParallaxProvider>
75-
<AppRoutes />
76-
</ParallaxProvider>
77-
);
78-
}
79-
}
80-
```
81-
82-
### Then: Create effects with useParallax()
83-
84-
Then import the `useParallax` hook and use it anywhere within the provider. Here's an example that uses the `speed` prop so simply speed up (or slowdown) the rate of scroll.
85-
86-
```jsx
87-
import { useParallax } from 'react-scroll-parallax';
43+
- [`useParallax()`](https://react-scroll-parallax.v3.damnthat.tv/docs/usage/hooks/use-parallax)
44+
- [`useController()`](https://react-scroll-parallax.v3.damnthat.tv/docs/usage/hooks/use-controller)
8845

89-
const Component = () => {
90-
const { ref } = useParallax({ speed: 10 });
91-
return <div ref={ref} className="my-thing" />;
92-
};
93-
```
94-
95-
### Or: Create effects with \<Parallax>
96-
97-
You can also use the `Parallax` component. Here's an example that will transform the element on the `translateY` axis starting at `-20%` and ending at `20%` (`translateY = [-20, 20]` \*percent is assumed with no provided unit).
98-
99-
```jsx
100-
import { Parallax } from 'react-scroll-parallax';
101-
102-
const Component = () => (
103-
<Parallax translateY={[-20, 20]}>
104-
<div className="my-thing" />
105-
</Parallax>
106-
);
107-
```
108-
109-
Example with transforms on the `translateX` axis starting at `-100px` and ending at `200px` (`translateX = ['-100px', '200px']`).
110-
111-
```jsx
112-
import { Parallax } from 'react-scroll-parallax';
113-
114-
const Component = () => (
115-
<Parallax translateX={['-100px', '200px']}>
116-
<div className="my-thing" />
117-
</Parallax>
118-
);
119-
```
120-
121-
## How it works
122-
123-
TODO: **Explain how and when effects are applied** with some illustrations and demos.
124-
125-
1. This lib was first designed to be used on elements that scroll naturally with the page. If you use `fixed` positioning you will likely want to set the `startScroll` and `endScroll` values manually, or use a `targetElement` to indicate scroll progress.
126-
2. Scroll state and positions of elements on the page are cached for performance reasons. This means that if the page height changes (most likely from [images loading](#example-usage-of-context)) after components mount the controller won't properly determine when the elements are in view. To correct this you can call the `parallaxController.update()` method from any child component of the `<ParallaxProvider />` via context. More details on how here: [Parallax Controller Context](#parallax-controller-context).
127-
128-
## Troubleshooting
129-
130-
If you're encountering issues like the parallax element jumping around or becoming stuck, there's a few likely culprits. Since this lib caches important positioning states it's possible for these to be outdated and incorrect. The most likely cause for this type of problem is the result of images loading and increasing the height of an element and/or the page. This can be fixed easily by [updating the cache](#example-usage-of-context).
131-
132-
## Optimizations to Reduce Jank
46+
### Docs: Components
13347

134-
Considerations have been taken to reduce jank -- [please read more here](https://parallax-controller.vercel.app/docs/performance) on how this is done
48+
- [`<Parallax>`](https://react-scroll-parallax.v3.damnthat.tv/docs/usage/components/parallax-component)
49+
- [`<ParallaxBanner>`](https://react-scroll-parallax.v3.damnthat.tv/docs/usage/components/parallax-banner-component)
50+
- [`<ParallaxProvider>`](https://react-scroll-parallax.v3.damnthat.tv/docs/usage/components/parallax-provider)

‎documentation/docs/intro.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ yarn add react-scroll-parallax@beta
3737
- [Usage](/docs/usage/)
3838
- [How it works](/docs/examples/how-it-works)
3939

40+
### Demos
41+
42+
- [Storybook v3](https://react-scroll-parallax-v3.surge.sh/) - [Source Code](https://github.com/jscottsmith/react-scroll-parallax/tree/v3/stories)
43+
- [Demo 1](https://jscottsmith.github.io/react-scroll-parallax-examples/examples/parallax-example/) - [Source Code (old 1.x version)](https://github.com/jscottsmith/react-scroll-parallax-examples)
44+
- [Demo 2](https://react-scroll-parallax.netlify.app/) - [Source Code (old 2.x version)](https://github.com/jscottsmith/react-parallax-site)
45+
4046
### Docs: Hooks
4147

4248
- [`useParallax()`](/docs/usage/hooks/use-parallax)

0 commit comments

Comments
 (0)