You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Optimizations to Reduce Jank](#optimizations-to-reduce-jank)
44
44
-[PSA](#psa)
45
45
46
-
## Usage
46
+
## Example Usage
47
47
48
48
The [`<ParallaxProvider>`](#parallaxprovider) must wrap the component tree that contains all `<Parallax>` components. This should be a top level component like `<App>`. For example:
1. This lib was designed to be used on `relative` or `absolute` positioned elements that scroll naturally with the page. If you use `fixed` positioning on either the element itself or the parent you will encounter issues. More on that in [troubleshooting](#troubleshooting).
91
91
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 `<Parallax />` components are mounted 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 and the `withController()` HOC. More details on how here: [Parallax Controller Context](#parallax-controller-context).
92
92
93
-
## \<Parallax>
94
-
95
-
The main component for manipulating a DOM element's position based on it's position within the viewport.
96
-
97
-
### Parallax Props
98
-
99
-
The following are all props that can be passed to the `<Parallax>` component:
|**x**|`string[]` or `number[]`|`[0, 0]`| Start and end translation on x-axis in `%` or `px`. If no unit is passed percent is assumed. Percent is based on the elements width. |
104
-
|**y**|`string[]` or `number[]`|`[0, 0]`| Start and end translation on y-axis in `%` or `px`. If no unit is passed percent is assumed. Percent is based on the elements height. |
105
-
|**className**|`string`|| Optionally pass additional class names to be added to the outermost parallax element. |
106
-
|**disabled**|`boolean`|`false`| Disables parallax effects on individual elements when `true`. |
107
-
|**styleInner**|`object`|| Optionally pass a style object to be added to the innermost parallax element. |
108
-
|**styleOuter**|`object`|| Optionally pass a style object to be added to the outermost parallax element. |
109
-
|**tagInner**|`string`|`div`| Optionally pass an element tag name to be applied to the innermost parallax element. |
110
-
|**tagOuter**|`string`|`div`| Optionally pass an element tag name to be applied to the outermost parallax element. |
111
-
112
-
## \<ParallaxBanner>
113
-
114
-
Component that utilizes `<Parallax>` components to achieve a parallaxing banner effect. Allows a single or multiple images to be parallaxed at different rates within the banner area.
115
-
116
-
### Banner Usage
117
-
118
-
Use the `layers` prop to indicate all images, offset amounts, and scroll rates. Optionally pass additional children to be rendered. Styles of the outermost banner element can also be changed. Here's an example:
119
-
120
-
```jsx
121
-
<ParallaxBanner
122
-
className="your-class"
123
-
layers={[
124
-
{
125
-
image:'https://foo.com/foo.jpg',
126
-
amount:0.1,
127
-
},
128
-
{
129
-
image:'https://foo.com/bar.png',
130
-
amount:0.2,
131
-
},
132
-
]}
133
-
style={{
134
-
height:'500px',
135
-
}}
136
-
>
137
-
<h1>Banner Children</h1>
138
-
</ParallaxBanner>
139
-
```
140
-
141
-
### Banner Props
142
-
143
-
The following are all props that can be passed to the `<ParallaxBanner>` component:
|**className**|`string`|| Optionally pass additional class names to be added to the outermost parallax banner element. |
148
-
|**disabled**|`boolean`|`false`| Determines if the internal parallax layers will have offsets applied. |
149
-
|**layers**|`array`|| A required `array` of `objects` with layer properties: `[{ amount: 0.1, image: 'foo.jpg' }]`. [See layers prop below](#banner-layers-prop)|
150
-
|**style**|`object`|| Optionally pass a style object to be added to the outermost parallax banner element. |
151
-
152
-
### Banner Layers Prop
153
-
154
-
The `layers` prop takes an array of objects that will represent each image (or custom children) of the parallax banner. The following properties describe a layer object:
|**amount**|`number`|| A value from `-1` to `1` that represents the vertical offset to be applied to the current layer, `0.1` would equal a `10%` offset on the top and bottom. |
159
-
|**children**|`ReactElement`|| Custom layer children provided as a React element, for example `<Video />`|
160
-
|**expanded**|`boolean`|`true`| Indicate if the layer should be expanded with negative top/bottom margins so the edges will never be visible. |
161
-
|**image**|`string`|| Image source that will be applied as a CSS background image on the layer. |
162
-
|**props**|`object`|| Props to apply to the layer element. Example: `{ props: style: { background: 'red' }}`|
163
-
164
-
## \<ParallaxProvider>
165
-
166
-
The `<ParallaxProvider />` component is meant to wrap a top level component in your application and is necessary to provide access though React context API to the parallax controller. This component should only be used once in you app, for instance in an `<AppContainer />` component that won't be mounted/unmounted during route changes. Like so:
167
-
168
-
```jsx
169
-
constAppContainer= () => (
170
-
<ParallaxProvider>
171
-
<Router>
172
-
<App />
173
-
</Router>
174
-
</ParallaxProvider>
175
-
);
176
-
```
177
-
178
-
### ParallaxProvider Props
179
-
180
-
The following props configure the `<ParallaxProvider>` component:
|**scrollAxis**|`string`|`vertical`| Optionally pass the scroll axis for setting horizontal/vertical scrolling. One of `vertical` or `horizontal`|
185
-
|**scrollContainer**|`HTMLElement`|`<body>`| Optionally set the container that has overflow and will contain parallax elements. Defaults to the HTML body |
186
-
187
-
### Parallax Controller Context
188
-
189
-
Access the controller via [React context](https://facebook.github.io/react/docs/context.html) in any components rendered within a `<ParallaxProvider>`.
190
-
191
-
This is accessible by using `useController()`[React hook](https://reactjs.org/docs/hooks-intro.html) in components without writing a class or wrapping them in HOC.
Access the following methods on `parallaxController` via context:
207
-
208
-
**`update()`**
209
-
210
-
Updates all cached attributes for parallax elements then updates their positions.
211
-
212
-
**`destroy()`**
213
-
214
-
Removes window scroll and resize listeners then resets all styles applied to parallax elements.
215
-
216
-
### Example usage of context
217
-
218
-
The most common use case that would require access to the controller is dealing with images. Since the controller caches attributes for performance they will need to be updated with the correct values once the image loads. Here's an example of how you could do that with an `<Image />` component:
If your parallax components are stuck and acting weird, this is most likely due to the fact that your page initial scroll was not at the top on load. Here's a possible solution to this problem using `useController()` hook. It can be used in your application top level component or specifically in the part of your application where you are experiencing problems.
// <ParallaxCache /> now can be used anywhere you have problems with cached attributes
249
-
```
250
-
251
93
## Troubleshooting
252
94
253
95
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). Another likely issue is the CSS positioning applied to the parent or parallax element itself is `fixed`. Fixed positioning parallax elements is currently not supported and may appear to work in some cases but break in others. Avoid using `position: fixed` and instead use `static`, `relative` or `absolute`, which this lib was designed to support. If none of these are relevant and you still have trouble please post an issue with your code or a demo that reproduces the problem.
Component that utilizes `<Parallax>` components to achieve a parallaxing banner effect. Allows a single or multiple images to be parallaxed at different rates within the banner area.
4
+
5
+
### Banner Usage
6
+
7
+
Use the `layers` prop to indicate all images, offset amounts, and scroll rates. Optionally pass additional children to be rendered. Styles of the outermost banner element can also be changed. Here's an example:
8
+
9
+
```jsx
10
+
<ParallaxBanner
11
+
className="your-class"
12
+
layers={[
13
+
{
14
+
image:'https://foo.com/foo.jpg',
15
+
amount:0.1,
16
+
},
17
+
{
18
+
image:'https://foo.com/bar.png',
19
+
amount:0.2,
20
+
},
21
+
]}
22
+
style={{
23
+
height:'500px',
24
+
}}
25
+
>
26
+
<h1>Banner Children</h1>
27
+
</ParallaxBanner>
28
+
```
29
+
30
+
### Banner Props
31
+
32
+
The following are all props that can be passed to the `<ParallaxBanner>` component:
|**className**|`string`|| Optionally pass additional class names to be added to the outermost parallax banner element. |
37
+
|**disabled**|`boolean`|`false`| Determines if the internal parallax layers will have offsets applied. |
38
+
|**layers**|`array`|| A required `array` of `objects` with layer properties: `[{ amount: 0.1, image: 'foo.jpg' }]`. [See layers prop below](#banner-layers-prop)|
39
+
|**style**|`object`|| Optionally pass a style object to be added to the outermost parallax banner element. |
40
+
41
+
### Banner Layers Prop
42
+
43
+
The `layers` prop takes an array of objects that will represent each image (or custom children) of the parallax banner. The following properties describe a layer object:
|**amount**|`number`|| A value from `-1` to `1` that represents the vertical offset to be applied to the current layer, `0.1` would equal a `10%` offset on the top and bottom. |
48
+
|**children**|`ReactElement`|| Custom layer children provided as a React element, for example `<Video />`|
49
+
|**expanded**|`boolean`|`true`| Indicate if the layer should be expanded with negative top/bottom margins so the edges will never be visible. |
50
+
|**image**|`string`|| Image source that will be applied as a CSS background image on the layer. |
51
+
|**props**|`object`|| Props to apply to the layer element. Example: `{ props: style: { background: 'red' }}`|
|**x**|`string[]` or `number[]`|`[0, 0]`| Start and end translation on x-axis in `%` or `px`. If no unit is passed percent is assumed. Percent is based on the elements width. |
12
+
|**y**|`string[]` or `number[]`|`[0, 0]`| Start and end translation on y-axis in `%` or `px`. If no unit is passed percent is assumed. Percent is based on the elements height. |
13
+
|**className**|`string`|| Optionally pass additional class names to be added to the outermost parallax element. |
14
+
|**disabled**|`boolean`|`false`| Disables parallax effects on individual elements when `true`. |
15
+
|**styleInner**|`object`|| Optionally pass a style object to be added to the innermost parallax element. |
16
+
|**styleOuter**|`object`|| Optionally pass a style object to be added to the outermost parallax element. |
17
+
|**tagInner**|`string`|`div`| Optionally pass an element tag name to be applied to the innermost parallax element. |
18
+
|**tagOuter**|`string`|`div`| Optionally pass an element tag name to be applied to the outermost parallax element. |
0 commit comments