README.md

Stickyroll

A sticky view with scroll listener API for parallax style views.

Table of Contents

• Getting started
• Basic usage
• Adjusting pages and factor usage
• Using listeners
• Using CSS variables
• Using ClassNames
• Using the hook
• Advanced usage
• Why we don't use States
• Typescript
• Testing

Getting started

Please install stickyroll and react. Stickyroll does not have any additional dependencies.

With NPM

npm install @stickyroll/react react react-dom

With Yarn

yarn add @stickyroll/react react react-dom

Basic usage

import Stickyroll from "@stickyroll/react/stickyroll";

export default function App() {
  return <Stickyroll pages={1}>Scroll here.</Stickyroll>;
}

Adjusting pages and factor usage

import Stickyroll from "@stickyroll/react/stickyroll";

export default function App() {
  return (
    // Uses 10 pages of 300vh each
    <Stickyroll pages={10} factor={3}>
      Scroll here.
    </Stickyroll>
  );
}

Using listeners

import Stickyroll from "@stickyroll/react/stickyroll";

export default function App() {
  return (
    <Stickyroll
      pages={1}
      onStart={() => {
        console.log("onStart");
      }}
      onPage={(page, index) => {
        console.log("onPage", page, index);
      }}
      onProgress={(progress, page, index) => {
        console.log("onProgress", progress, page, index);
      }}
      onEnd={() => {
        console.log("onEnd");
      }}
    >
      Scroll here.
    </Stickyroll>
  );
}

Using CSS variables

• height: CSS_VARS.height
• pages: CSS_VARS.pages
• factor: CSS_VARS.factor
• progress: CSS_VARS.progress
• page: CSS_VARS.page

import Stickyroll from "@stickyroll/react/stickyroll";
import { CSS_VARS } from "@stickyroll/react/constants";

export default function App() {
  return (
    <Stickyroll pages={1}>
      <div
        style={{
          height: 10,
          background: "red",
          transform: `scaleX(var(${CSS_VARS.progress}, 0))`,
        }}
      />
    </Stickyroll>
  );
}

Using ClassNames

• root: CLASS_NAMES.root
• above: CLASS_NAMES.above
• below: CLASS_NAMES.below
• sticky: CLASS_NAMES.sticky
• nonSticky: CLASS_NAMES.nonSticky
• page: CLASS_NAMES.page (type: function)

import styled from "@emotion/styled";
import Stickyroll from "@stickyroll/react/stickyroll";
import { CLASS_NAMES } from "@stickyroll/react/constants";

const StyledComponent = styled.div`
  height: 10px;
  background: red;

  /* Active while in sticky mode */
  &.${CLASS_NAMES.sticky} {
    background: yellow;
  }

  /* Active before sticky mode */
  &.${CLASS_NAMES.above} {
    background: blue;
  }

  /* Active after sticky mode */
  &.${CLASS_NAMES.below} {
    background: hotpink;
  }

  /* Active while on page 0 (index) */
  &.${CLASS_NAMES.page(0)} {
    background: rebeccapurple;
  }
`;

export default function App() {
  return (
    <Stickyroll pages={1}>
      <StyledComponent />
    </Stickyroll>
  );
}

Using the hook

import { CSS_VARS, STYLE } from "@stickyroll/react/constants";
import useStickyroll from "@stickyroll/react/use-stickyroll";
import { useRef } from "react";

export default function App() {
  const ref = useRef();
  useStickyroll(ref, { pages: 1 });
  return (
    <div
      ref={ref}
      style={{
        height: `var(${CSS_VARS.height}, var(--100vh, 100vh))`,
      }}
    >
      <div style={STYLE}>Scroll here.</div>
    </div>
  );
}

Advanced usage

You can provide your own styles and behavior to adjust stickyroll to your needs. Take a look at the examples:

• Demo
• Source

Why we don't use States

While you can write the output of stickyroll to a state we recommend to work without states, to optimize performance.

You can access the ref (see the example) and modify the styles and additional behavior from there.

If you still need a state, we recommend using a global state that can then be accessed in child components to prevent re-rendering the top level component.

You can take a look at these state management libraries or use your own preferred library:

• Zustand
• Jotai

Typescript

Stickyroll provides types and is fully typed. Use them, don't use them… if you ever need them, we've got you covered.

Testing

We test stickyroll in real browsers with real interactions to ensure full coverage and reliability of this library.