react-magnetic-scroll

react magnetic scroll component

Usage no npm install needed!

<script type="module">
  import reactMagneticScroll from 'https://cdn.skypack.dev/react-magnetic-scroll';
</script>

README

react-magnetic-scroll

A magic pagination component to navigate with magnetic scroll navigation current version : 1.3.0

Breaking changes

From v1.3 to v1.4 :

  • Scroll is more optimal & smooth. Check out duration set.
  • Fix mount of bugs, including scroll bar. Enables possibility to navigate through pages using the scroll bar.

From v1.2 to v1.3 :

  • Now import MagneticScroll using braces { }
  • Default import still available but deprecated and soon unavailable.

Using the component :

  1. Install the component :

yarn add react-magnetic-scroll

  1. Import the component that way :

import { MagneticScroll, MagneticPage } from 'react-magnetic-scroll';

  1. Call the component by injecting options :
  • define pages : use the MagneticPage component
const page1 = (
  <MagneticPage id="page1">
    <div id="panda">
      <p>page 1</p>
    </div>
  </MagneticPage>
);
const page2 = (
  <MagneticPage id="page2">
    <div id="flying_fish">
      <p>page 2</p>
    </div>
  </MagneticPage>
);
const page3 = (
  <MagneticPage id="page2">
    <div id="birthdaycake">
      <p>page 3</p>
    </div>
  </MagneticPage>
);

const pages = [page1, page2, page3];

Please note id property is required

  • display magnetic scroll :
  <MagneticScroll pages={pages} {...props} />
  • scroll to page :

    • add 'ref' property
    • add 'withRef' property
    • call scrollTo with the n° of page as argument
  <MagneticScroll
    ref={magneticScroll => { this.magneticScroll = magneticScroll; }}
    withRef
    pages={{pages}}
    {...props}
  />
  const gotoPage = (page = 2) =>
    this.magneticScroll.scrollTo(page);

how it works

MagneticScroll uses an array of components, views, etc... and display them in "magnetic pages" that have similar width & height. On scroll, keydown & touchmove events, the natural scroll is blocked and the magnetic container autoscroll to the next page.

Values are expressed in viewheights (vh) and viewwidths (vw).

You need to wrap your pages with a component MagneticPage that requires an ID and can handle hooks before and after scroll.

properties :

REQUIRED :

  • pages PropTypes.arrayOf(PropTypes.Node)

OPTIONAL :

  • pageHeight PropTypes.number (default = 100)
  • pageWidth PropTypes.number (default = 100)
  • onPageChangeStart PropTypes.func (default = void)
  • onPageChangeEnd PropTypes.func (default = void)
  • onScrollUpStart PropTypes.func (default = void)
  • onScrollUpEnd PropTypes.func (default = void)
  • onScrollDownStart PropTypes.func (default = void)
  • onScrollDownEnd PropTypes.func (default = void)
  • easing PropTypes.string (default = linear),
  • duration PropTypes.number (default = 500)
  • increment PropTypes.number (default = 10)
  • delay PropTypes.number (default = 0)
  • disabled *PropTypes.bool (default = false)
  • debounce *PropTypes.number (default = 600)
  • style *PropTypes.shape (default = {})
  • pageStyle *PropTypes.bool (default = {})

EASING :

Values available :

  • linear
  • easeInOut
  • easeInQuad
  • easeOutQuad
  • easeInOutQuad
  • easeInCubic
  • easeOutCubic
  • easeInOutCubic
  • easeInCirc
  • easeOutCirc
  • easeInOutCirc
  • easeInQuint
  • easeOutQuint
  • easeInOutQuint
  • easeInExpo
  • easeOutExpo
  • easeInOutExpo

MagneticPage properties :

  • ID : PropTypes.string.isRequired
  • onScrollUpStart : PropTypes.func (default: void)
  • onScrollUpEnd : PropTypes.func (default: void)
  • onScrollDownStart : PropTypes.func (default: void)
  • onScrollDownEnd : PropTypes.func (default: void)

When are hooks triggered ?

  • start : on scroll from the current page
  • end : on arriving on the current page (from the previous one)

Example App

It's often the case that you want to test your components out with an example app before publishing.

Included in this setup is a setup to do just that.

Getting Started

  1. cd example/app && yarn
  2. Within the example/app directory, you will find a setup that you can use to test your app. Import your components from components and use them within the App.js file.
  3. Run npm run start and navigate to http://localhost:3000 to see your app

Dev roadmap :

Coming soon v1.5 :

  • Possibility to set up custom easing transitions functions
  • Add more easing transitions functions (bounce, etc...)
  • Add horizontal scrolling & pagination (hot !!)
  • Add controls and exceptions for bad entries
  • Set up pre-commit hooks

Later...

  • Writing unit tests :)