npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-waypoint-decorator

v2.0.0

Published

Decorator to apply waypoints to React components

Downloads

15

Readme

react-waypoint-decorator

Decorator to apply waypoints to React components

Travis npm

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.

Table of contents

Installation

npm install react-waypoint-decorator

This package has one peer dependency, React:

{
  "peerDependencies": {
    "react": ">=16.2.0"
  }
}

Usage

The Basics

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);

Output HTML

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>

Passing Options

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 {}

Deriving Options from Props

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 {}

Responding to Activation

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
    }
  }
}

Component Version

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.

API

waypoint(options)

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.

<Waypoint />

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.

Local Development

git clone https://github.com/ueno-llc/react-waypoint-decorator
cd react-waypoint-decorator
npm install
npm test

License

MIT © ueno.