Svelte Locomotive Scroll

A locomotive-scroll wrapper for Svelte
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 svelte-locomotive-scroll

or using Yarn

$ yarn add locomotive-scroll svelte-locomotive-scroll

Usage

1. Import the provider

import LocomotiveScrollProvider from 'svelte-locomotive-scroll'

2. Wrap your application using the provider

<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
      //  I.e. in Sveltekit you would want to watch properties like `$page` imported from '$app/stores' (you may want to add more criterias if the instance should be update on locations with query parameters)
    ]
  }
>
    {/* ...your app */}
</LocomotiveScrollProvider>

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

    <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

//Get the context with the key of 'locomotiveScroll'
const { getScroll } = getContext('locomotiveScroll');

//call the function getScroll to get the actual Scroll Instance provided by the Wrapper
const scrollInstance = getScroll();

  // ... your component
}

Now you should be able to utilize the ful functionality of the scroll object.

For more examples and how 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 changes but not when the rest of your dependencies added to the watch list change, there's an option:

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

svelte-locomotive-scroll will update the scroll instance as it should, but apply different 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={$page.url}
  onLocationChange={(scroll) => scroll.scrollTo(0, { duration: 2, disableLerp: false })} // If you want to reset the scroll position to 0 for example
>
  {/* ...your app */}
</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

Jason Thompson - [email protected]

Project Link: https://github.com/jasonandrewth/svelte-locomotive-scroll

Acknowledgements

• react-locomotive-scroll

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