Decorator to apply waypoints to React components
react-waypoint is a library that allows you to run code when an element scrolls into view. This is a decorator that wraps a React component in a waypoint, and passes down an activated
prop to that component the first time it scrolls into view. It's especially handy for animating elements in as the user scrolls down the page.
npm install react-waypoint-decorator
This package has one peer dependency, React:
{
"peerDependencies": {
"react": ">=16.2.0"
}
}
This is the most basic form of a scroll trigger. This component will receive an activated
prop, which is either true
or false
depending on if the component has scrolled into view yet. By default, "scrolled into view" means that the top edge of the element is at least halfway up the page. You can fine-tune this threshold by passing an options object to the decorator.
import React, { Component } from 'react';
import waypoint from 'react-waypoint-decorator';
@waypoint()
export default class Box extends Component {
render() {
if (this.props.activated) {
return <p>You can see me!</p>;
}
return <p>You can't see me yet.</p>;
}
}
Note that this example uses the experimental decorator syntax. If you use Babel to transpile JavaScript, you can add decorator support with the decorators transform plugin.
If your setup doesn't support decorators, you can also call the decorator as a function.
import React, { Component } from 'react';
import waypoint from 'react-waypoint-decorator';
class Box extends Component {
render() {
if (this.props.activated) {
return <p>You can see me!</p>;
}
return <p>You can't see me yet.</p>;
}
}
export default waypoint()(Box);
The new component created by the decorator will wrap your component and its waypoint in a plain <div />
. This means your component will now be block-level, and generally fill the width of its container. Keep this in mind when adding waypoints, particularly if you use a grid system. If you style a component to have a percentage width, and then wrap it in a waypoint, the percentage width won't be applied, because the component is now wrapped in a full-width <div />
.
<div>
<Waypoint />
<YourComponent />
</div>
You can pass an object of options to the decorator to customize the waypoint. For example, the activatedProp
option lets you change the name of the "activated" prop passed to the component. Refer to the full list of options below.
@waypoint({
activatedProp: 'visible',
offset: 25,
})
class Box extends Component {}
Instead of passing an object to the waypoint()
decorator, you can also pass a function gets the component props as a parameter, and returns options.
@waypoint(props => ({
offset: props.offset,
}))
class Box extends Component {}
To run code when a component scrolls into view, use componentDidUpdate()
. Or, to update state in response to the scroll event, use getDerivedStateFromProps()
.
@waypoint
class Box extends Component {
componentDidUpdate(prevProps) {
if (!prevProps.activated && this.props..activated) {
// If we're here, then the component has scrolled into view for the first time
}
}
}
The decorator tracks the scroll position of the entire component. If you only want to monitor a specific chunk of a component, we've got you covered with the <Waypoint />
component.
import React, { Component } from 'react';
import { Waypoint } from 'react-waypoint-decorator';
export default class Box extends Component {
render() {
return (
<div>
<p>This part of the component isn't being monitored.</p>
<Waypoint>
{activated => (
<p>But this part is.{activated && ' And it\'s scrolled into view!'}</p>
)}
</Waypoint>
</div>
);
}
}
The <Waypoint />
component takes a render function as a child. The function has one parameter, activated
, which is true
or false
depending on if that chunk of HTML has scrolled into view yet.
Create a waypoint decorator with custom settings.
- options (object|function): waypoint settings. It can be an object or a function that takes props and returns an object. Either way, the object can have any of these properties:
- autoRun (boolean): trigger the waypoint immediately, regardless of where it is when the page loads. Useful if you have something above the fold that needs to animate in no matter what.
- activatedProp (string): name of boolean prop to pass to wrapped component. Default is
activated
. - offset (number): percentage offset from the bottom of the window that triggers a waypoint. The default is
50
, which means the top edge of the component must be 50% of the way up the screen to trigger the waypoint. Higher numbers make components trigger later, while lower numbers make them trigger sooner. - wrapper (function): HTML to wrap the waypoint and component in. By default it's a
<div />
. To change this, pass a function to this object that takes one parameter,children
, and returns JSX.
Returns a decorated React component.
React component that wraps the output of a render function in a waypoint. The render function takes these parameters:
- activated (boolean): if the component has scrolled into view yet.
The <Waypoint />
component takes these props:
- autoRun (boolean): trigger the waypoint immediately, regardless of where it is when the page loads. Useful if you have something above the fold that needs to animate in no matter what.
- offset (number): percentage offset from the bottom of the window that triggers a waypoint. The default is
50
, which means the top edge of the component must be 50% of the way up the screen to trigger the waypoint. Higher numbers make components trigger later, while lower numbers make them trigger sooner. - wrapper (function): HTML to wrap the waypoint and component in. By default it's a
<div />
. To change this, pass a function to this object that takes one parameter,children
, and returns JSX.
git clone https://github.com/ueno-llc/react-waypoint-decorator
cd react-waypoint-decorator
npm install
npm test
MIT © ueno.