Skip to content

A simple and easy to use tiny library that provides useSwipe hook to use with React that enables swipe gestures for touch screens

Notifications You must be signed in to change notification settings

rajatkantinandi/useSwipe

Repository files navigation

useSwipe hook

NPM

A simple and easy to use tiny library that provides useSwipe hook to use with React that enables swipe gestures for touch screens & non-touch screens via mouse events

Install

npm i use-swipe-hook

Usage

import React, { useRef } from 'react';
import ReactDOM from 'react-dom';
import './styles.css';
import { useSwipe } from 'use-swipe-hook';

function App() {
  const swipeContainerRef = useRef<HTMLDivElement>(null);
  const direction = useSwipe({ ref: swipeContainerRef, thresholdPX: 5 });

  return (
    <div className="App">
      <h1>use-swipe-hook demo</h1>
      <h2>Works on both touch & non touch devices (by dragging mouse over the container)</h2>
      <div className="swipeContainer" ref={swipeContainerRef}>
        {direction ? `You have swiped ${direction}` : 'Swipe here to see swipe direction'}
      </div>
    </div>
  );
}

const rootElement = document.getElementById('root');
ReactDOM.render(<App />, rootElement);

Advanced Usage

Version 2 introduces 2 new hooks for advanced usage.

useSwipeVector - Get magnitude & direction of your swipe along with origin

import React, { useRef } from 'react';
import ReactDOM from 'react-dom';
import './styles.css';
import { useSwipeVector } from 'use-swipe-hook';

function UseSwipeVector() {
  const swipeContainerRef = useRef<HTMLDivElement>(null);
  const {
    magnitude,
    direction,
    origin: { x, y },
  } = useSwipeVector({
    ref: swipeContainerRef,
    thresholdPX: 5,
    unit: 'deg',
    useRelativeUnits: true,
  });

  return (
    <div className="swipeContainer vector axis" ref={swipeContainerRef}>
      {magnitude ? (
        <>
          You have swiped {magnitude.toFixed(2)}px towards {direction.toFixed(0)}&deg; starting from ({x.toFixed(0)},{' '}
          {y.toFixed(0)})
        </>
      ) : (
        'Swipe here to see swipe direction'
      )}
    </div>
  );
}

const rootElement = document.getElementById('root');
ReactDOM.render(<UseSwipeVector />, rootElement);

useSwipePosition - Get raw co-ordinates of your swipe including start & end position

import React, { useRef } from 'react';
import ReactDOM from 'react-dom';
import './styles.css';
import { useSwipePosition } from 'use-swipe-hook';

function UseSwipePosition() {
  const swipeContainerRef = useRef<HTMLDivElement>(null);
  const { x1, y1, x2, y2 } = useSwipePosition({
    ref: swipeContainerRef,
    thresholdPX: 5,
    useRelativeUnits: true,
  });

  return (
    <div className="swipeContainer position axis" ref={swipeContainerRef}>
      {x1 ? (
        <>
          You have swiped from ({x1.toFixed(0)}, {y1.toFixed(0)}) to ({x2.toFixed(0)}, {y2.toFixed(0)})
        </>
      ) : (
        'Swipe here to see swipe direction'
      )}
    </div>
  );
}

const rootElement = document.getElementById('root');
ReactDOM.render(<UseSwipePosition />, rootElement);

Code splitting

The library uses code splitting, so even though 2 new hooks are introduced in version 2 and the overall bundle size is slightly increased, the individual hook bundle size remains small when you use a single hook on you application. This means more features but still leaner & tiny bundle size.

Structure

// SWIPE_DIRECTION can be imported & used for comparison
enum SWIPE_DIRECTION {
  RIGHT = 'right',
  LEFT = 'left',
  UP = 'up',
  DOWN = 'down',
}

interface UseSwipeOptions {
  // ref of the container where you want to attach swipe event
  ref: RefObject<HTMLElement>;
  // (optional) no of pixels to move your finger to trigger a swipe event.
  // Larger this value means less sensitivity. Default value is 5 (5px)
  thresholdPX?: number;
}

const useSwipe: ({ ref, thresholdPX }: UseSwipeOptions) => SWIPE_DIRECTION | null;

interface UseSwipeVectorOptions {
  // ref of the container where you want to attach swipe event
  ref: RefObject<HTMLElement>;
  // (optional) no of pixels to move your finger to trigger a swipe event.
  // Larger this value means less sensitivity. Default value is 5 (5px)
  thresholdPX?: number;
  unit?: 'rad' | 'deg'; // unit of direction for useSwipeVector hook
  // whether to use position units based relative to canvas rather than with respect to window
  useRelativeUnits?: boolean;
}

const useSwipeVector: ({ ref, thresholdPX, unit, useRelativeUnits }: UseSwipeVectorOptions) => SWIPE_DIRECTION | null;

interface UseSwipePositionOptions {
  // ref of the container where you want to attach swipe event
  ref: RefObject<HTMLElement>;
  // (optional) no of pixels to move your finger to trigger a swipe event.
  // Larger this value means less sensitivity. Default value is 5 (5px)
  thresholdPX?: number;
  // whether to use position units based relative to canvas rather than with respect to window
  useRelativeUnits?: boolean;
}

const useSwipePosition: ({ ref, thresholdPX, useRelativeUnits }: UseSwipePositionOptions) => SWIPE_DIRECTION | null;

Demo

Codesandbox demo

GitHub actions for type-checking, building & auto-publish

This repo uses github actions to publish a package when:

  • a new pull request is merged to master
    • When a pull request is merged or something is pushed to master then if src folder has file changes then only it will publish a version.
    • Additionally the merge commit message should contain [publish] keyword otherwise it will not publish on merge & just do build time checks.
    • Also while running the action one needs to increment the version number in package.json before merging the PR otherwise the npm publish command will fail.
  • can be triggered manually.

On any other branch commits it will run type-check & build checks if src folder files are changed.

© rajatkantinandi

About

A simple and easy to use tiny library that provides useSwipe hook to use with React that enables swipe gestures for touch screens

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published