react-parent-bound-drag v1.2.2

useBoundedDrag

A React hook that provides drag functionality with configurable boundaries, directions, and thresholds. This hook supports both touch and pointer events, and allows for customizing the drag behavior, including restricting movement to certain axes or ranges.

Installation

You can install this package via npm:

npm install react-parent-bound-drag

Or via yarn:

yarn add react-parent-bound-drag

Usage

This hook enables draggable elements in React, allowing you to control the drag direction (x, y, or both), set thresholds to prevent small accidental drags, and limit the draggable area.

Example

import React from 'react';
import { useBoundedDrag } from 'react-parent-bound-drag';  // Import the hook

const DraggableBox = () => {
  const {
    onTouchStart,
    onTouchMove,
    onTouchEnd,
    onPointerMove,
    onPointerDown,
    onPointerUp,
  } = useBoundedDrag({
    direction: '',  // Allow dragging in both X and Y directions
    threshold: 10,  // Minimum threshold before drag starts
    range: {
      x: { min: 0, max: 300 },  // Limit dragging in X axis between 0 and 300 pixels
      y: { min: 0, max: 300 },  // Limit dragging in Y axis between 0 and 300 pixels
    },
    onDrag: (e) => {
      console.log('Dragging...', e);
    },
    onDragStart: (e) => {
      console.log('Drag started', e);
    },
    onDragEnd: (e) => {
      console.log('Drag ended', e);
    },
  });

  return (
    <div
      style={{ width: '400px', height: '400px', border: '1px solid black', position: 'relative' }}
    >
      <div
        onPointerDown={onPointerDown}
        onPointerMove={onPointerMove}
        onPointerUp={onPointerUp}
        onTouchStart={onTouchStart}
        onTouchMove={onTouchMove}
        onTouchEnd={onTouchEnd}
        style={{
          width: '100px',
          height: '100px',
          backgroundColor: 'lightblue',
          position: 'absolute',
        }}
      >
        Drag Me
      </div>
    </div>
  );
};

export default DraggableBox;

Example Explanation

useBoundedDrag Hook: This hook handles both touch and pointer events for dragging. It provides handlers for drag events (onTouchStart, onTouchMove, onPointerDown, etc.) which should be attached to the draggable element.

Direction: The direction prop controls whether the element can be dragged along the 'x', 'y', or '' axes. In this example, '' allows free movement in both axes.

Threshold: The threshold option sets the minimum distance the user must drag before the drag action begins. In this case, a drag won't start until the user moves the element by 10 pixels.

Range: The range option restricts the draggable area. In this example, the element is limited to moving between 0 and 300 pixels on both the X and Y axes. If -1 is specified as the max value for either axis, the drag will be unrestricted on that axis. If no range is specified, the element is constrained to the parent element's boundaries.

API

Hook: useBoundedDrag

Arguments

The hook accepts an optional configuration object with the following properties:

range Object

The range object allows you to specify the boundaries for the draggable element:

range: {
  x?: { max?: number, min?: number },  // Limits dragging on the X axis
  y?: { max?: number, min?: number },  // Limits dragging on the Y axis
}

• x: Specifies the minimum (min) and maximum (max) values for dragging along the X axis.
• y: Specifies the minimum (min) and maximum (max) values for dragging along the Y axis.

Returned Values

The useBoundedDrag hook returns a set of event handlers that you should attach to the draggable element.

Example Usage: Direction Control

If you want to restrict the dragging direction to only the X axis, you can configure it like this:

const { onPointerDown, onPointerMove, onPointerUp } = useBoundedDrag({
  direction: 'x',  // Only allow dragging in the X direction
});

Or if you want to restrict it to the Y axis:

const { onPointerDown, onPointerMove, onPointerUp } = useBoundedDrag({
  direction: 'y',  // Only allow dragging in the Y direction
});

License

This project is licensed under the MIT License.