react-swipeable

What is react-swipeable?

The react-swipeable package is a React component that provides easy-to-use swipe event handlers for touch devices. It allows developers to add swipe functionality to their React components, making it ideal for creating touch-friendly user interfaces.

What are react-swipeable's main functionalities?

Basic Swipe Detection

This code demonstrates how to use the react-swipeable package to detect basic swipe events. The `useSwipeable` hook is used to create swipe handlers, which are then applied to a div element. When a swipe is detected, a message is logged to the console.

import React from 'react';
import { useSwipeable } from 'react-swipeable';

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

  return (
    <div {...handlers} style={{ width: '100%', height: '100px', background: 'lightgray' }}>
      Swipe here
    </div>
  );
};

export default SwipeComponent;

Swipe Direction Detection

This code demonstrates how to detect the direction of a swipe using the react-swipeable package. The `useSwipeable` hook is configured with handlers for each swipe direction (left, right, up, down), and logs a message to the console when a swipe in that direction is detected.

import React from 'react';
import { useSwipeable } from 'react-swipeable';

const SwipeDirectionComponent = () => {
  const handlers = useSwipeable({
    onSwipedLeft: () => console.log('Swiped Left!'),
    onSwipedRight: () => console.log('Swiped Right!'),
    onSwipedUp: () => console.log('Swiped Up!'),
    onSwipedDown: () => console.log('Swiped Down!')
  });

  return (
    <div {...handlers} style={{ width: '100%', height: '100px', background: 'lightblue' }}>
      Swipe in any direction
    </div>
  );
};

export default SwipeDirectionComponent;

Swipe Threshold Configuration

This code demonstrates how to configure a swipe threshold using the react-swipeable package. The `useSwipeable` hook is configured with a `delta` value, which sets the minimum distance (in pixels) that a swipe must cover to be detected.

import React from 'react';
import { useSwipeable } from 'react-swipeable';

const SwipeThresholdComponent = () => {
  const handlers = useSwipeable({
    onSwiped: (eventData) => console.log('User Swiped!', eventData),
    delta: 50 // Minimum distance (in pixels) for a swipe to be detected
  });

  return (
    <div {...handlers} style={{ width: '100%', height: '100px', background: 'lightgreen' }}>
      Swipe with a minimum threshold
    </div>
  );
};

export default SwipeThresholdComponent;

Other packages similar to react-swipeable

react-swipe

The react-swipe package provides a React component for touch slide navigation. It is similar to react-swipeable in that it allows for swipe detection, but it is more focused on creating swipeable carousels and sliders. It offers a higher-level abstraction compared to react-swipeable.

react-use-gesture

The react-use-gesture package is a set of hooks for handling gestures in React. It supports a wide range of gestures, including swipes, pinches, and scrolls. Compared to react-swipeable, react-use-gesture offers more comprehensive gesture support and can be used for more complex interactions.

react-swipeable-views

The react-swipeable-views package is a React component for creating swipeable views, such as tabs or carousels. It is similar to react-swipeable in that it provides swipe detection, but it is specifically designed for creating swipeable view containers. It offers built-in support for animations and transitions.

README

React Swipeable

React swipe and touch event handler component

Github Pages Demo

Installation

$ npm install --save react-swipeable

Use

import Swipeable from 'react-swipeable'

class SwipeComponent extends React.Component {

  swiping(e, deltaX, deltaY, absX, absY, velocity) {
    console.log("You're Swiping...", e, deltaX, deltaY, absX, absY, velocity)
  }

  swipingLeft(e, absX) {
    console.log("You're Swiping to the Left...", e, absX)
  }

  swiped(e, deltaX, deltaY, isFlick, velocity) {
    console.log("You Swiped...", e, deltaX, deltaY, isFlick, velocity)
  }

  swipedUp(e, deltaY, isFlick) {
    console.log("You Swiped Up...", e, deltaY, isFlick)
  }

  render() {
    return (
      <Swipeable
        onSwiping={this.swiping}
        onSwipingLeft={this.swipingLeft}
        onSwiped={this.swiped}
        onSwipedUp={this.swipedUp} >
          You can swipe here!
      </Swipeable>
    )
  }
}

react-swipeable(<Swipeable>) generates a new React element(<div> by default) under the hood and binds touch events to it that are used to fire the swiping and swiped props.

Props / Config Options

Event Props

onSwiping, onSwipingUp, onSwipingRight, onSwipingDown, onSwipingLeft, are called with the event as well as the absolute delta of where the swipe started and where it's currently at. These constantly fire throughout touch events.

onSwiping in addition to the swipe delta, onSwiping also returns the current absolute X and Y position, as well as the current velocity of the swipe. this.props.onSwiping(e, deltaX, deltaY, absX, absY, velocity)

onSwipedUp, onSwipedRight, onSwipedDown, onSwipedLeft are called with the event as well as the x distance, + or -, from where the swipe started to where it ended. These only fire at the end of a touch event.

onSwiped is called with the event, the X and Y delta, whether or not the event was a flick, and the current velocity of the swipe. this.props.onSwiped(e, deltaX, deltaY, isFlick, velocity)

onTap is triggered when a tap happens, specifically when a swipe/touch moves less than the delta. Is called with the onTouchEnd event this.props.onTap(e)

Configuration Props

flickThreshold is a number (float) which determines the max velocity of a swipe before it's considered a flick. The default value is 0.6.

delta is the amount of px before we start firing events. Also affects how far onSwipedUp, onSwipedRight, onSwipedDown, and onSwipedLeft need to be before they fire events. The default value is 10.

preventDefaultTouchmoveEvent is whether to prevent the browser's touchmove event. Sometimes you would like the target to scroll natively. The default value is false.

• Notes e.preventDefault() is only called when preventDefaultTouchmoveEvent is true and the user is swiping in a direction that has an associated directional onSwiping or onSwiped prop.
  • Example: user is swiping right with <Swipable onSwipedRight={this.userSwipedRight} preventDefaultTouchmoveEvent={true} > then e.preventDefault() will be called, but if user was swiping left e.preventDefault() would not be called.
  • Please experiment with example to test preventDefaultTouchmoveEvent.
  • swipeable versions < 4.2.0 - Chrome 56 and later, warning with preventDefault

stopPropagation automatically calls stopPropagation on all 'swipe' events. The default value is false.

nodeName is a string which determines the html element/node that this react component binds its touch events to then returns. The default value is 'div'.

trackMouse will allow mouse 'swipes' to additonally be tracked(click, hold, move, let go). See #51 for more details. The default value is false.

disabled will disable <Swipeable>: swipes will not be tracked and this stops current active swipes from triggering anymore prop callbacks. The default value is false.

innerRef will allow access to the Swipeable's inner dom node element react ref. See #81 for more details. Example usage <Swipeable innerRef={(el) => this.swipeableEl = el} >. Then you'll have access to the dom element that Swipeable uses internally.

rotationAngle will allow to set a rotation angle, e.g. for a four-player game on a tablet, where each player has a 90° turned view. The default value is 0.

None of the props are required.

PropType Definitions

Event Props:

  onSwiped: PropTypes.func,
  onSwiping: PropTypes.func,
  onSwipingUp: PropTypes.func,
  onSwipingRight: PropTypes.func,
  onSwipingDown: PropTypes.func,
  onSwipingLeft: PropTypes.func,
  onSwipedUp: PropTypes.func,
  onSwipedRight: PropTypes.func,
  onSwipedDown: PropTypes.func,
  onSwipedLeft: PropTypes.func,
  onTap: PropTypes.func,

Config Props:

  flickThreshold: PropTypes.number, // default: 0.6
  delta: PropTypes.number, // default: 10
  preventDefaultTouchmoveEvent: PropTypes.bool, // default: false
  stopPropagation: PropTypes.bool, // default: false
  nodeName: PropTypes.string // default: div
  trackMouse: PropTypes.bool, // default: false
  disabled: PropTypes.bool, // default: false
  innerRef: PropTypes.func,
  rotationAngle: PropTypes.number // default: 0

Development

Initial set up, with node 8+, run npm install.

Make changes/updates to the src/Swipeable.js file.

Before creating a PR please run npm test to make sure the tests and lint pass.

• Please add tests if PR adds/changes functionality.

Test changes/updates with the examples

Build, run, and test examples locally: npm run start:examples

After the server starts you can then view the examples page with your changes at http://localhost:3000.

You can now make updates/changes to src/Swipeable.js and webpack will rebuild, then reload the page so you can test your changes!

Notes

Chrome 56 and later, warning with preventDefault

swipeable version >=4.2.0 should fix this issue. PR here.

The issue still exists in versions <4.2.0:

• When this library tries to call e.preventDefault() in Chrome 56+ a warning is logged:
• Unable to preventDefault inside passive event listener due to target being treated as passive.

This warning is because this change to Chrome 56+ and the way the synthetic events are setup in reactjs.

Follow reacts handling of this issue here: facebook/react#8968

License

MIT