react-swipeable

To implement swipe functionality in your React application, follow these three steps:

1. Import the useSwipeable hook from react-swipeable.
2. Configure the swipe handlers by passing an options object to useSwipeable (e.g., defining onSwiped).
3. Spread the returned handlers object onto the HTML element you want to track swipes on.

This binds the necessary touch and mouse events to that specific element.

import { useSwipeable } from 'react-swipeable';

const handlers = useSwipeable({
    onSwiped: (eventData) => console.log("User Swiped!", eventData),
  ...config,
});

return <div {...handlers}> You can swipe here </div>;

To run the example applications on your local machine, navigate to the examples directory and execute the following commands using yarn:

1. Install dependencies: yarn
2. Start the development server: yarn start

The examples can also be viewed online at http://stack.formidable.com/react-swipeable/ or explored via CodeSandbox.

yarn && yarn start

Use the preventScrollOnSwipe prop to stop the browser from scrolling while a user is swiping.

When preventScrollOnSwipe is true, Swipeable calls e.preventDefault() on the touchmove event. This only occurs if:

1. preventScrollOnSwipe is true.
2. trackTouch is true.
3. The current swipe has an associated onSwiping or onSwiped handler/prop.

Important Notes:

• preventScrollOnSwipe supersedes touchEventOptions.passive for the touchmove listener. When true, the touchmove listener is set to { passive: false } to allow preventDefault(). Other listeners remain { passive: true }.
• If you need all listeners to be passive for performance, consider using the CSS touch-action property on the container instead of using this prop.

To generate the static version of the documentation site, run yarn build. This command produces static content in the build directory, which can then be hosted on any static content hosting service.

$ yarn build

To run the documentation site for development, install the dependencies using yarn and then start the local development server with yarn start. The development server supports live reloading, so most changes will be reflected in the browser immediately without a restart.

$ yarn
$ yarn start

To attach swipe functionality to the entire document instead of a specific DOM element, you can manually pass the document object to the ref returned by useSwipeable.

Important: You must clean up the event listeners by calling ref({}) in the useEffect cleanup function to prevent memory leaks or unexpected behavior.

const { ref } = useSwipeable({
  ...
}) as { ref: RefCallback<Document> };

useEffect(() => {
  ref(document);
  // Clean up swipeable event listeners
  return () => ref({});
});

If you need to use both the ref provided by useSwipeable (to attach swipe handlers) and your own ref (to access the DOM element), you can use a ref passthrough function. Instead of passing a useRef object directly to the ref prop, pass a function that calls handlers.ref(el) and then assigns the element to your own ref.

const MyComponent = () => {
  const handlers = useSwipeable({ onSwiped: () => console.log('swiped') })

  // setup ref for your usage
  const myRef = React.useRef();

  const refPassthrough = (el) => {
    // call useSwipeable ref prop with el
    handlers.ref(el);

    // set myRef el so you can access it yourself
    myRef.current = el;
  }

  return (<div {...handlers} ref={refPassthrough} />)
}

To prevent the page (or body) from scrolling while a user is swiping an element, you can use the CSS touch-action property. This is often a simpler and more performant alternative to using the preventScrollOnSwipe option in react-swipeable (which relies on event.preventDefault() during onTouchMove).

Refer to the MDN documentation for touch-action to choose the appropriate CSS value for your specific interaction model.

When upgrading from version 6 to version 7, the primary breaking change involves the renaming of the property used to control scroll prevention during swipe gestures.

Replace preventDefaultTouchmoveEvent with preventScrollOnSwipe. This prop provides the same functionality but with a more explicit name. In v7, this prop specifically controls the passive event listener option for touchmove events to ensure correct behavior.

const handlers = useSwipeable({
-  preventDefaultTouchmoveEvent: true,
+  preventScrollOnSwipe: true,
});