Skip to content

Commit 3b7ee10

Browse files
jscottsmithjscottsmith
committed
README and description updates
1 parent 0e5192c commit 3b7ee10

File tree

2 files changed

+36
-19
lines changed

2 files changed

+36
-19
lines changed

‎README.md

Lines changed: 33 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![npm version](https://badge.fury.io/js/react-scroll-parallax.svg)](https://badge.fury.io/js/react-scroll-parallax) [![Build Status](https://travis-ci.org/jscottsmith/react-scroll-parallax.svg?branch=master)](https://travis-ci.org/jscottsmith/react-scroll-parallax) [![codecov](https://codecov.io/gh/jscottsmith/react-scroll-parallax/branch/master/graph/badge.svg)](https://codecov.io/gh/jscottsmith/react-scroll-parallax)
44

5-
Provides a React component and single passive scroll listener to add **vertical** scrolling based offsets to elements based on their position in the viewport. Works with universal (server-side rendered) React apps.
5+
Provides React components to create parallax scroll effects for banners, images or any other DOM elements. Uses a single scroll listener to add **vertical** scrolling based offsets to elements based on their position in the viewport. [Optimized](#optimizations-to-reduce-jank) to _reduce_ jank on scroll and works with universal (server-side rendered) React apps.
66

77
## Examples
88

@@ -28,6 +28,22 @@ or yarn
2828
yarn add react-scroll-parallax
2929
```
3030

31+
## Overview
32+
33+
* [Usage](#usage)
34+
* [`<Parallax>`](#parallax)
35+
* [Parallax Props](#parallax-props)
36+
* [`<ParallaxBanner>`](#parallax)
37+
* [Banner Usage](#banner-usage)
38+
* [Banner Props](#banner-props)
39+
* [Banner Layers Prop](#banner-layers-prop)
40+
* [`<ParallaxProvider>`](#parallaxprovider)
41+
* [Parallax Controller Context](#parallax-controller-context)
42+
* [Available Methods](#available-methods)
43+
* [Browser Support](#browser-support)
44+
* [Optimizations to Reduce Jank](#optimizations-to-reduce-jank)
45+
* [PSA](#psa)
46+
3147
## Usage
3248

3349
The [`<ParallaxProvider>`](#parallaxprovider) should wrap the component tree that contains all `<Parallax>` components. This should be a top level component like `<AppContainer>`. For example:
@@ -68,9 +84,9 @@ const ParallaxImage = () => (
6884

6985
## \<Parallax>
7086

71-
The main component for manipulating an element's position based on scroll position within the viewport.
87+
The main component for manipulating a DOM element's position based on it's position within the viewport.
7288

73-
### Props
89+
### Parallax Props
7490

7591
The following are all props that can be passed to the `<Parallax>` component:
7692

@@ -89,11 +105,11 @@ The following are all props that can be passed to the `<Parallax>` component:
89105

90106
## \<ParallaxBanner>
91107

92-
Component that utilizes `<Parallax>` components to achieve a parallaxing banner effect.
108+
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.
93109

94-
### Example Usage
110+
### Banner Usage
95111

96-
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:
112+
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:
97113

98114
```jsx
99115
<ParallaxBanner
@@ -118,20 +134,20 @@ Use the `layers` prop to indicate all images, offset amounts and scroll rates. O
118134
</ParallaxBanner>
119135
```
120136

121-
### Props
137+
### Banner Props
122138

123139
The following are all props that can be passed to the `<ParallaxBanner>` component:
124140

125-
| Name | Type | Default | Description |
126-
| ------------- | :-------: | :------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
127-
| **className** | `String` | | Optionally pass additional class names to be added to the outermost parallax banner element. |
128-
| **disabled** | `Boolean` | `false` | Determines if the internal parallax layers will have offsets applied. |
129-
| **layers** | `Array` | | A required `Array` of `Objects` with layer properties: `[{ amount: 0.1, image: 'foo.jpg', slowerScrollRate: false }]`. [See layers prop below](#layers-prop) |
130-
| **style** | `Object` | | Optionally pass a style object to be added to the outermost parallax banner element. |
141+
| Name | Type | Default | Description |
142+
| ------------- | :-------: | :------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
143+
| **className** | `String` | | Optionally pass additional class names to be added to the outermost parallax banner element. |
144+
| **disabled** | `Boolean` | `false` | Determines if the internal parallax layers will have offsets applied. |
145+
| **layers** | `Array` | | A required `Array` of `Objects` with layer properties: `[{ amount: 0.1, image: 'foo.jpg', slowerScrollRate: false }]`. [See layers prop below](#banner-layers-prop) |
146+
| **style** | `Object` | | Optionally pass a style object to be added to the outermost parallax banner element. |
131147

132-
### Layers Prop
148+
### Banner Layers Prop
133149

134-
The `layers` props takes an array of objects that will represent each image of the parallax banner. The following properties describe a layer:
150+
The `layers` prop takes an array of objects that will represent each image of the parallax banner. The following properties describe a layer object:
135151

136152
| Name | Type | Description |
137153
| -------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -222,6 +238,6 @@ React scroll parallax should support the last two versions of all major browsers
222238

223239
React Scroll Parallax uses a single [passive scroll listener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Improving_scrolling_performance_with_passive_listeners) (dependent on browser support) with the minimal amount of work done on the scroll event to prevent [jank](http://jankfree.org/) (calculations that cause layout, reflow and paint are cached initially and only updated when layout changes). Request animation frame is then used to decouple the scroll handler and further reduce jank. All offsets are applied with 3D transforms to utilize the GPU and prevent paints. If you have ideas to further optimize scrolling please PR or post an issue.
224240

225-
**PSA**
241+
### **PSA**
226242

227-
It's 2017 and you probably shouldn't be building parallax sites—but if you do (like I did) and you use this package try and use it responsibly. Keeping images small and optimized, reducing the number of moving elements in view and on the page, and disabling scroll effects on mobile devices should keep scrolling smooth.
243+
Even with these optimizations scroll effects can cause jank. If you use this lib make sure to keep images small and optimized, reduce the number of moving elements in view and on the page in total, and disable scroll effects on mobile devices. That should keep scrolling smooth and users happy.

‎package.json

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "react-scroll-parallax",
33
"version": "1.3.0",
4-
"description": "React component to create parallax scrolling effects",
4+
"description": "React components to create parallax scroll effects for banners, images or any other DOM elements.",
55
"repository": {
66
"type": "git",
77
"url": "https://github.com/jscottsmith/react-scroll-parallax"
@@ -27,8 +27,9 @@
2727
},
2828
"keywords": [
2929
"react",
30-
"parallax",
3130
"scroll",
31+
"parallax",
32+
"banner",
3233
"animation",
3334
"component"
3435
],

0 commit comments

Comments
 (0)