Drag-Based Component for Slider, Carousel, Scroller (Dragdealer)

Download   Demo

JS API

Here are the options, callbacks and methods Dragdealer supports, but you can read the source code for more information.

Constructor

• Dragdealer(wrapper, options=) Accepts an id or a DOM reference for the wrapper element. See possible options below.

Options

• bool disabled=false Init Dragdealer in a disabled state. The handle will have a .disabled class.


• bool horizontal=true Enable horizontal dragging.


• bool vertical=false Enable vertical dragging.


• number x=0 Initial horizontal (left) position. Accepts a float number value between 0 and 1.


• number y=0 Initial vertical (top) position. Accepts a float number value between 0 and 1.


• number steps=0 Limit the positioning of the handle within the bounds of the wrapper, by defining a virtual grid made out of a number of equally-spaced steps. This restricts placing the handle anywhere in-between these steps. E.g. setting 3 steps to a regular slider will only allow you to move it to the left, to the right or exactly in the middle.


• bool snap=false When a number of steps is set, snap the position of the handle to its closest step instantly, even when dragging.


• bool slide=true Slide handle after releasing it, depending on the movement speed before the mouse/touch release.


• bool loose=false Loosen-up wrapper boundaries when dragging. This allows the handle to be *slightly* dragged outside the bounds of the wrapper, but slides it back to the margins of the wrapper upon release.


• number top=0 Top padding between the wrapper and the handle.


• number bottom=0 Bottom padding between the wrapper and the handle.


• number left=0 Left padding between the wrapper and the handle.


• number right=0 Right padding between the wrapper and the handle.


• fn callback(x, y) Called when releasing handle, with the projected x, y position of the handle. Projected value means the value the slider will have after finishing a sliding animation, caused by either a step restriction or drag motion (see steps and slide options.)


• fn animationCallback(x, y) Called every animation loop, as long as the handle is being dragged or in the process of a sliding animation. The x, y positional values received by this callback reflect the exact position of the handle DOM element, which includes exceeding values (even negative values) when the loose option is set true.


• string handleClass=handle Custom class of handle element.


• bool css3=true Use css3 transform in modern browsers instead of absolute positioning.


• bool requestAnimationFrame=false Animate with requestAnimationFrame or setTimeout polyfill instead of default setInterval animation.

Methods

• disable Disable dragging of a Dragdealer instance. Just as with the disabled option, the handle will receive a .disabled class


• enable Enable dragging of a Dragdealer instance. The .disabled class of the handle will be removed.


• reflow Recalculate the wrapper bounds of a Dragdealer instance, used when the wrapper is responsive and its parent container changed its size, or after changing the size of the wrapper directly.


• getValue Get the value of a Dragdealer instance programatically. The value is returned as an [x, y] tuple and is the equivalent of the projected value returned by the regular callback, not animationCallback.


• getStep Same as getValue, but the value returned is in step increments (see steps option)


• setValue(x, y, snap=false) Set the value of a Dragdealer instance programatically. The 3rd parameter allows to snap the handle directly to the desired value, without any sliding transition.


• setStep(x, y, snap=false) Same as setValue, but the value is received in step increments (seesteps option)

Just a slider

A slider is just a user control, the power lies in the value it represents. For this reason theanimationCallback is your biggest ally, with it you tie the user input to any visualization you can think of. This is the most boring example.

new Dragdealer('just-a-slider', 
 animationCallback: function(x, y) 
 $('#just-a-slider .value').text(Math.round(x * 100));
 
);

Content scroller

Controlling a different element is a straightforward use-case for Dragdealer. It’s basic math. Let’s spice it up with some vertical movement.

var availHeight = $('.content-body').outerHeight() -
 $('.content-mask').outerHeight();
new Dragdealer('content-scroller', 
 horizontal: false,
 vertical: true,
 yPrecision: availHeight,
 animationCallback: function(x, y) 
 $('.content-body').css('margin-top', -y * availHeight);
 
);

“slide to unlock”

This is how this project started, somebody wanted an iPhone-like slider. Classic.

new Dragdealer('slide-to-unlock-old', 
 steps: 2,
 callback: function(x, y) 
 // Only 0 and 1 are the possible values because of "steps: 2"
 if (x) 
 this.disable();
 $('#slide-to-unlock-old').fadeOut();
 
 
);

Image carousel

Let’s kick it up a notch. How about a touch-ready image carousel… piece of cake. The entire string of images will be the draggable handle, masked by a wrapper the size of a single image (a slide.)

new Dragdealer('image-carousel', 
 steps: 4,
 speed: 0.3,
 loose: true,
 requestAnimationFrame: true
);

Interactive canvas mask

With Dragdealer you can go from creating a simple slider to an entire website. I’m only saying this because I’ve seen more than a few examples of full-window implementations.

var canvasMask = new Dragdealer('canvas-mask', 
 x: 0,
 // Start in the bottom-left corner
 y: 1,
 vertical: true,
 speed: 0.2,
 loose: true,
 requestAnimationFrame: true
);

// Bind event on the wrapper element to prevent it when a drag has been made
// between mousedown and mouseup (by stopping propagation from handle)
$('#canvas-mask').on('click', '.menu a', function(e) 
 e.preventDefault();
 var anchor = $(e.currentTarget);
 canvasMask.setValue(anchor.data('x'), anchor.data('y'));
);

 

Drag-Based Component for Slider, Carousel, Scroller (Dragdealer)