React Locomotive Scroll

A locomotive-scroll React wrapper
Explore Locomotive Scroll docs »

Report Bug · Request Feature

Table of Contents

1. Getting Started
   • Prerequisites
   • Installation
2. Usage
3. Specific cases
4. Contributing
5. License
6. Contact
7. Acknowledgements

Getting Started

To get a local copy up and running follow these simple steps.

Installation

$ npm install locomotive-scroll @studio-freight/react-locomotive-scroll

or using Yarn

$ yarn add locomotive-scroll @studio-freight/react-locomotive-scroll

Usage

1. Import the provider

import { LocomotiveScrollProvider } from '@studio-freight/react-locomotive-scroll'

2. Wrap your application using the provider

const containerRef = useRef(null)

<LocomotiveScrollProvider
  options={
    {
      smooth: true,
      // ... all available Locomotive Scroll instance options 
    }
  }
  watch={
    [
      //..all the dependencies you want to watch to update the scroll.
      //  Basicaly, you would want to watch page/location changes
      //  For exemple, on Next.js you would want to watch properties like `router.asPath` (you may want to add more criterias if the instance should be update on locations with query parameters)
    ]
  }
  containerRef={containerRef}
>
  <main data-scroll-container ref={containerRef}>
    {/* ...your app */}
  </main>
</LocomotiveScrollProvider>

3. Wrap your pages using data-scroll-section to prevent weird behaviours

export function Page() {
  return (
    <div data-scroll-section>
      {/* ...your page */}
    </div>
  )
}

From the Locomotive Scroll doc : Defines a scrollable section. Splitting your page into sections may improve performance. You may want to use data-scroll-section on each page which may be wrapped by LocomotiveScrollProvider

4. Add the base styles to your CSS file.

locomotive-scroll.css

5. Get the scroll instance through all your components

import { useLocomotiveScroll } from '@studio-freight/react-locomotive-scroll'

export function Component() {
  const { scroll } = useLocomotiveScroll()

  // ... your component
}

At this time you should be able to do whatever your want using the scroll object.

For more examples and to use Locomotive Scroll, please refer to their Documentation

Specific cases

1. Apply code to the location update only

If you want to write some code applied only when the location change but not when the rest of your dependencies added to the watch list change, here the thing:

First, remove the location props from the watch dependencies list and add it to the location props.

@studio-freight/react-locomotive-scroll will update the scroll instance as it should, but in a different useEffect than the one used to update watched dependencies

const { pathname } = useLocation() // With react-router
const { asPath } = useRouter() // With next/router

<LocomotiveScrollProvider
  options={
    {
      smooth: true,
      // ... all available Locomotive Scroll instance options 
    }
  }
  watch={
    [
      //...all the dependencies you want to watch to update the scroll EXCEPT the location one
    ]
  }
  location={asPath}
  containerRef={containerRef}
  onLocationChange={scroll => scroll.scrollTo(0, { duration: 0, disableLerp: true })} // If you want to reset the scroll position to 0 for example
  onUpdate={() => console.log('Updated, but not on location change!')} // Will trigger on 
>
  <main data-scroll-container ref={containerRef}>
    {/* ...your app */}
  </main>
</LocomotiveScrollProvider>

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Antoine Lin - @vahilloff - [email protected]

Project Link: https://github.com/@studio-freight/react-locomotive-scroll

Acknowledgements

Please feel free to open a pull request to add your project to the list!