Drag-handler NPM

Drag Handler

A tiny (1kb gzipped), high-performance, zero-dependency mouse/touch event wrapper for handling drag interactions. Useful for creating drag and drop interactions or detecting swipes on a touch device. Inspired by Matt Hinchliffe.

Installation

npm i drag-handler --save

Usage

import { createDragHandler } from 'drag-handler'

// Get a target element
let targetElement = document.getElementById('hasDragEvents');

// Create the handler by passing the element to createDragHandler
let handler = createDragHandler(targetElement);

// Attach event listeners
handler.on('dragstart' (e: CustomEvent<DragGesture>) => {
	// Do something at the start of the drag
});

handler.on('drag' (e: CustomEvent<DragGesture>) => {
	// Do something during the drag interaction
});

handler.on('dragend' (e: CustomEvent<DragGesture>) => {
	// Do something at the end of the drag
});

Handler.on Arguments

Name	Type	Description
eventName	`string`	The event name to listen for
callback	`function`	The event listener callback function

Handler Event Names

Name	Description
`"dragstart"`	Triggered on the initial touchstart/mousedown event
`"drag"`	Triggered between dragstart and dragend when the pointer position moves
`"dragend"`	Triggered on the next touchend/mouseup event, when the drag is finished

Handler Event Details

Each handler event will include a DragGesture object as the event details. This object contains several pieces of information about the drag event.

handler.on('drag' (e: CustomEvent<DragGesture>) => {
	let { distance, direction, position, timeStamp, velocity } = e.details;
});

DragGesture

Property	Type	Description
direction	object	The direction of the drag from the previous gesture
distance	object	The horizontal and vertical distance from the first gesture
elementPoint	object	The position of the drag event relative to the element
windowPoint	object	The position of the drag event relative to the window
timeStamp	number	The event timestamp in milliseconds
velocity	object	The velocity of the drag from the previous gesture

DragGesture.direction

Property	Type	Description
x	string, null	If not null, the horizontal direction as a string "left" or "right"
y	string, null	If not null, the vertical direction as a string "up" or "down"

DragGesture.distance

Property	Type	Description
x	number	The horizontal distance from the first event in px
y	number	The vertical distance from the first event in px

DragGesture.elementPoint

Property	Type	Description
x	number	The horizontal coordinate of the touch/mouse event relative to the element
y	number	The vertical coordinate of the touch/mouse event relative to the element

DragGesture.windowPoint

Property	Type	Description
x	number	The horizontal coordinate of the touch/mouse event relative to the page
y	number	The vertical coordinate of the touch/mouse event relative to the page

DragGesture.velocity

Property	Type	Description
x	number	The horizontal velocity of the gesture
y	number	The vertical velocity of the gesture

Example Usages

Dragging and dropping an element

import { createDragHandler } from 'drag-handler'

let draggable = document.getElementById('myDraggableElement');
let handler = createDragHandler(draggable);

handler.on('drag' (e: CustomEvent<DragGesture>) => {
	let { x, y } = e.details.distance;
	draggable.style.transform = `translate3d(${x}px, ${y}px, 0)`;
});

Dragging and swiping horizontal carousel slides

import { createDragHandler } from 'drag-handler'

let carousel = new ExampleCarouselLibrary('#myCarousel');
let handler = createDragHandler(carousel.viewport as HTMLElement);
let paginationDistance = carousel.width() / 3;

handler.on('drag' (e: CustomEvent<DragGesture>) => {
	let { x } = e.details.distance;
	carousel.activeSlide.style.transform = `translate3d(${x}px, 0, 0)`;
});

handler.on('dragend' (e: CustomEvent<DragGesture>) => {
	if(Math.abs(e.details.distance.x) > paginationDistance) {
		let direction = e.details.direction.x;
		if(direction === 'left') carousel.slideNext();
		if(direction === 'right') carousel.slidePrevious();
	} else {
		carousel.activeSlide.style.transform = 'none';
	}
});