search

desandro / draggabilly

:point_down: Make that shiz draggable
https://draggabilly.desandro.com
MIT License
3.86k stars 386 forks source link

readme

Draggabilly

Make that shiz draggable

draggabilly.desandro.com

Rad because it supports mouse and touch devices.

Draggabilly v3.0.0

Install

Download

Package managers

Install with npm: npm install draggabilly

Install with Yarn: yarn add draggabilly

CDN

Link directly to draggabilly.pkgd.min.js on unpkg.com.

<script src="https://unpkg.com/draggabilly@3/dist/draggabilly.pkgd.min.js"></script>

Usage

Initialize Draggabilly as a jQuery plugin

var $draggable = $('.draggable').draggabilly({
  // options...
})

Initialize Draggabilly with vanilla JS

var elem = document.querySelector('.draggable');
var draggie = new Draggabilly( elem, {
  // options...
});

// or pass in selector string as first argument
var draggie = new Draggabilly( '.draggable', {
  // options...
});

// if you have multiple .draggable elements
// get all draggie elements
var draggableElems = document.querySelectorAll('.draggable');
// array of Draggabillies
var draggies = []
// init Draggabillies
for ( var i=0; i < draggableElems.length; i++ ) {
  var draggableElem = draggableElems[i];
  var draggie = new Draggabilly( draggableElem, {
    // options...
  });
  draggies.push( draggie );
}

Classes

Options

axis

Type: String

Values: 'x' or 'y'

axis: 'x'

Constrains movement to horizontal or vertical axis.

containment

Type: Element, Selector String, or Boolean

containment: '.container'

Contains movement to the bounds of the element. If true, the container will be the parent element.

grid

Type: Array

Values: [ x, y ]

grid: [ 20, 20 ]

Snaps the element to a grid, every x and y pixels.

handle

Type: Selector String, Array, HTMLElement

// select all .handle children with selector string
handle: '.handle'

// set as element
handle: element.querySelector('.handle')

// set as array or NodeList
handle: [ element.querySelector('.handle1'), element.querySelector('.handle2') ]

Specifies on what element the drag interaction starts.

handle is useful for when you do not want all inner elements to be used for dragging, like inputs and forms. See back handle example on CodePen.

Events

Bind events with jQuery with standard jQuery event methods .on(), .off(), and .one(). Inside jQuery event listeners this refers to the Draggabilly element.

// jQuery
function listener(/* parameters */) {
  // get Draggabilly instance
  var draggie = $(this).data('draggabilly');
  console.log( 'eventName happened', draggie.position.x, draggie.position.y );
}
// bind event listener
$draggable.on( 'eventName', listener );
// unbind event listener
$draggable.off( 'eventName', listener );
// bind event listener to trigger once. note ONE not ON
$draggable.one( 'eventName', function() {
  console.log('eventName happened just once');
});

Bind events with vanilla JS with .on(), .off(), and .once() methods. Inside vanilla JS event listeners this refers to the Draggabilly instance.

// vanilla JS
function listener(/* parameters */) {
  console.log( 'eventName happened', this.position.x, this.position.y );
}
// bind event listener
draggie.on( 'eventName', listener );
// unbind event listener
draggie.off( 'eventName', listener );
// bind event listener to trigger once. note ONCE not ONE or ON
draggie.once( 'eventName', function() {
  console.log('eventName happened just once');
});

dragStart

Triggered when dragging starts and the element starts moving. Dragging starts after the user's pointer has moved a couple pixels to allow for clicks.

// jQuery
$draggable.on( 'dragStart', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'dragStart', function( event, pointer ) {...})

dragMove

Triggered when dragging moves.

// jQuery
$draggable.on( 'dragMove', function( event, pointer, moveVector ) {...})
// vanilla JS
draggie.on( 'dragMove', function( event, pointer, moveVector ) {...})

dragEnd

Triggered when dragging ends.

// jQuery
$draggable.on( 'dragEnd', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'dragEnd', function( event, pointer ) {...})

pointerDown

Triggered when the user's pointer (mouse, touch, pointer) presses down.

// jQuery
$draggable.on( 'pointerDown', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'pointerDown', function( event, pointer ) {...})

pointerMove

Triggered when the user's pointer moves.

// jQuery
$draggable.on( 'pointerMove', function( event, pointer, moveVector ) {...})
// vanilla JS
draggie.on( 'pointerMove', function( event, pointer, moveVector ) {...})

pointerUp

Triggered when the user's pointer unpresses.

// jQuery
$draggable.on( 'pointerUp', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'pointerUp', function( event, pointer ) {...})

staticClick

Triggered when the user's pointer is pressed and unpressed and has not moved enough to start dragging.

click events are hard to detect with draggable UI, as they are triggered whenever a user drags. Draggabilly's staticClick event resolves this, as it is triggered when the user has not dragged.

// jQuery
$draggable.on( 'staticClick', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'staticClick', function( event, pointer ) {...})

Methods

disable

// jQuery
$draggable.draggabilly('disable')
// vanilla JS
draggie.disable()

enable

// jQuery
$draggable.draggabilly('enable')
// vanilla JS
draggie.enable()

setPosition

// jQuery
$draggable.draggabilly( 'setPosition', x, y )
// vanilla JS
draggie.setPosition( x, y )

dragEnd

Stop dragging.

// jQuery
$draggable.draggabilly('dragEnd')
// vanilla JS
draggie.dragEnd()

destroy

// jQuery
$draggable.draggabilly('destroy')
// vanilla JS
draggie.destroy()

jQuery.fn.data('draggabilly')

Get the Draggabilly instance from a jQuery object. Draggabilly instances are useful to access Draggabilly properties.

var draggie = $('.draggable').data('draggabilly')
// access Draggabilly properties
console.log( 'draggie at ' + draggie.position.x + ', ' + draggie.position.y )

Properties

position

draggie.position
// => { x: 20, y: -30 }

Webpack & Browserify

Install Draggabilly with npm.

npm install draggabilly
var Draggabilly = require('draggabilly');

var draggie = new Draggabilly( '.draggable', {
  // options
});

To use Draggabilly as a jQuery plugin, you need to install and call jQuery Bridget.

npm install jquery-bridget
var $ = require('jquery');
var jQueryBridget = require('jquery-bridget');
var Draggabilly = require('draggabilly');

// make Draggabilly a jQuery plugin
jQueryBridget( 'draggabilly', Draggabilly, $ );
// now you can use $().draggabilly()
$('.draggable').draggabilly({...})

Browser support

Draggabilly v3 supports Chrome 49+, Firefox 41+, Safari 14+ (mobile & desktop), and Edge 12+.

License

Draggabilly is released under the MIT License. Have at it.

Made by David DeSandro 😻