React Scroll Snapper

A library for creating swipeable views using CSS scroll snap.

Originally developed as a replacement for the react-swipeable-views which is not compatible with latest React and no longer maintained.

You might not need this library

If you don't need to control the current page from JavaScript, you can use a simple scrollable div with following styles:

.ScrollSnapper {
  display: flex;
  scroll-snap-type: x mandatory;
  overflow-x: scroll;
  scroll-behavior: smooth;
}

.ScrollSnapper > * {
  box-sizing: border-box; /* if not set globally */
  width: 100%;
  flex-shrink: 0;
  scroll-snap-align: center;
  scroll-snap-stop: always;
}

Then use it in your JSX:

function App() {
  return (
    <div className="ScrollSnapper">
      <div>Page 1</div>
      <div>Page 2</div>
      <div>Page 3</div>
    </div>
  )
}

Here are the same styles in Tailwind CSS:

function App() {
  return (
    <div
      className={
        "flex snap-x snap-mandatory overflow-x-scroll scroll-smooth " +
        "*:w-full *:flex-shrink-0 *:snap-center *:snap-always"
      }
    >
      <div>Page 1</div>
      <div>Page 2</div>
      <div>Page 3</div>
    </div>
  )
}

To implement tabs which scroll to different pages when clicked, you can use anchors which point to the page ids:

function App() {
  return (
    <>
      <ul>
        <li>
          <a href="#page1">Page 1</a>
        </li>
        <li>
          <a href="#page2">Page 2</a>
        </li>
        <li>
          <a href="#page3">Page 3</a>
        </li>
      </ul>

      <div className="ScrollSnapper">
        <div id="page1">Page 1</div>
        <div id="page2">Page 2</div>
        <div id="page3">Page 3</div>
      </div>
    </>
  )
}

If you don't need to react to a page change from user, but want to scroll to a page programmatically, you can use the scrollIntoView method on the page element:

function App() {
  const scrollSnapperRef = useRef<HTMLDivElement>(null)

  return (
    <>
      <p>
        <button onClick={() => scrollSnapperRef.current?.children[0]?.scrollIntoView()}>
          First page
        </button>
        <button onClick={() => scrollSnapperRef.current?.children[2]?.scrollIntoView()}>
          Last page
        </button>
      </p>
      <div className="ScrollSnapper" ref={scrollSnapperRef}>
        <div>Page 1</div>
        <div>Page 2</div>
        <div>Page 3</div>
      </div>
    </>
  )
}

Importing styles

You can import only the styles from this library and use them with the snippets above.

Import the styles in your HTML:

<link rel="stylesheet" href="react-scroll-snapper/index.css" />

or in your CSS:

@import "react-scroll-snapper/index.css";

or in your JavaScript if your bundler supports it:

import "react-scroll-snapper/index.css"

Tip

You can also import the styles from esm.sh or similar CDN.

That way you don't need to install this library in your node_modules and you can use the styles without any build tools.

<link rel="stylesheet" href="https://esm.sh/react-scroll-snapper/index.css" />

Using the React component

You can use the ScrollSnapper component to easily bind the current page index to your React state:

import "react-scroll-snapper/index.css"
import { ScrollSnapper } from "react-scroll-snapper"
import { useState } from "react"

function App() {
  const [pageIndex, setPageIndex] = useState(0)

  return (
    <ScrollSnapper index={pageIndex} onIndexChange={setPageIndex}>
      <div>Page 1</div>
      <div>Page 2</div>
      <div>Page 3</div>
    </ScrollSnapper>
  )
}

Tip

Consider simply copy-pasting the component's source code into your project. It's very small and easy to maintain and doesn't have any dependencies. You can also add any additional features you need yourself.

See example/index.tsx for a more complete example.

Tips

How to hide the scrollbar?

Add scrollbar-width: none to the container:

.noScrollbar {
  scrollbar-width: none;
}

For Safari:

.noScrollbar::-webkit-scrollbar {
  display: none;
}

Usage:

<ScrollSnapper className="noScrollbar">...</ScrollSnapper>

How to remove empty space when current page is shorter than the others?

You can set max-height on the container and add overflow-y: scroll to the pages.

.scrollChildren {
  max-height: 384px;
}

.scrollChildren > * {
  overflow-y: scroll;
}

<ScrollSnapper className="scrollChildren">...</ScrollSnapper>

Developing

• npm start: Start the example app using vite.
• npm run prepare: Build the library using tsc.
• npm test: Check code using tsc.

API

ScrollSnapper()

ScrollSnapper(props): Element

Scroll Snapper React component.

Parameters

Parameter	Type
props	ScrollSnapperProps & HTMLProps<HTMLDivElement>

Returns

Element

---

ScrollSnapperProps

Props for the ScrollSnapper component.

Properties

Property	Type	Description
index	number	The current page index. Can be changed to programmatically scroll to a different page.
onIndexChange	(index: number, target: HTMLDivElement) => void	A callback which runs after the container is scrolled to a page. This will run even if the user scrolled but ended up on the same page. Scrolling triggered by changing the index prop will also trigger this callback after the animation is finished.