When you pair GreenSock's Draggable with ThrowPropsPlugin, you get the ultimate tag-team for making a DOM element draggable, spinnable, tossable, and even flick-scrollable! You can impose bounds, complex snapping rules, and have things glide to a stop in a silky-smooth way, all with as little as one line of code! No kidding. Works great on touch devices too. Below you'll find 3 examples of what Draggable can do when it's got some ThrowPropsPlugin love under the hood. Check out the code samples too (they auto-update as you change options).
Throw
By default, Draggable uses type:"x,y" meaning it'll use css transforms for positional movement (hardware accelerated when possible).
Activate the some of the snapping options below and watch how nicely things glide into place exactly on the grid or snap into place as you drag. Notice the edge resistance as you try
to drag past the edges; everything is configurable. [ View this on codepen.io ]
- Options
Draggable.create(".box", {
type: "x,y",
edgeResistance: 0.65,
bounds: "#container",
throwProps: true
});
Spin
Set Draggable's type to "rotation" and watch what happens (grab the knob below and spin it). ThrowPropsPlugin tracks the velocity of the rotation and continues when you release your mouse (or finger for touch devices), gliding to a stop naturally. Activate the "Snap to 90-degree increments" option to see how easy it is to make it always land at certain rotational values without any jerking or awkwardness.
Draggable.create("#knob", {type: "rotation", throwProps: true});
Scroll (Drag & Flick)
Draggable can even be used to control the scrollTop and/or scrollLeft properties of an element, complete with overscrolling, snap-back, momentum continuation, and edge resistance.
It's as simple as changing the type to "scroll". And Draggable doesn't use artificial scrollbars like some other tools - it uses native scrolling with the standard OS/browser scrollbar UI. Play with the demo below and see for yourself.
Drag me to scroll me
Click and drag this content and then let go as you're dragging to throw it. Notice how it smoothly glides
to a rest, respecting the initial velocity and even permitting overscolling with bounce-back without forcing
fake/simulated scrollbars. It's actually using the scrollTop or scrollLeft of the container, and then if/when
it exceeds the bounds, it'll apply a translate3d() transform for hardware-accelerated performance, and it'll
even fall back to using padding when 3D transforms aren't available. Yes, it even works in IE8!
How does it work?
When you create the Draggable with type:"scroll" (or "scrollTop" or "scrollLeft"), it will create a
<div> and wrap it around the native content of the target element so that it can move things appropriately.
So that wrapper div ends up being the only child of the element. Then, as you drag, it updates the scrollTop/scrollLeft
of the element until you exceed the bounds at which time it'll either add a translate3d() CSS transform
(if supported) to that wrapper <div> or fall back to using padding for older browsers.
This gives you the best of both worlds - it delivers native scrolling with normal
scrollbar UI that's built into the OS/browser, plus outstanding performance on mobile devices due to the
translate3d() sweetness on overscroll, and compatibility even with IE8, all in a 3.4k gzipped footprint
(not including TweenLite or CSSPlugin which are required).
Oh, and don't forget the kinetic-based flick scrolling that's enabled when you load ThrowPropsPlugin and
set throwProps:true in the config object. When you drag past the normal scrolling limits, the edgeResistance
kicks in (you control how much). It just "feels" natural and fluid, much more so than most other options out there.
Did we mention Draggable works great with touch events too? And if the user flick-scrolls and then while it's animating, they use their mouse wheel or grab the scrollbar to take control themselves, Draggable automatically releases control and stops the animation. Don't worry your pretty little head.
Usage
Setup is a breeze. One line is all you need:
Draggable.create("#container", {type:"scroll", throwProps:true, edgeResistance:0.35});
That's it!
Of course you can tweak the configuration however you please. Want to only scroll vertically?
Use type:"scrollTop". Or for horizontal scrolling, use type:"scrollLeft". When you use simply
type:"scroll", it allows scrolling in either direction.
Change the edgeResistance to 1 if you don't want the user to be able to drag past the edge.
Note that ThrowPropsPlugin is a membership benefit of Club GreenSock ("Shockingly Green" and "Business Green" levels), but the Draggable works fine without that - you just won't get the kinetic-based motion. You can still drag things.
Not just for scrolling
As you can see from the examples above, Draggable is multi-talented. Change the type to "x,y" to make
the entire object draggable around the screen (literally moving it, not scrolling). Or type:"top,left" does the same thing,
but uses the "top" and "left" css properties instead of translateX() and translateY() CSS transforms.
Or if you want to be able to drag-spin an object, use type:"rotation". In fact, it'll even honor the
transform-origin of the element.
- Options
Draggable.create("#scroller", {type:"scroll", edgeResistance:0.5, throwProps:true});
Features
- Touch enabled - works great on tablets, phones, and desktop browsers.
- Incredibly smooth - GPU-accelerated and requestAnimationFrame-driven for ultimate performance. Compared to other options out there,
Draggablejust feels far more natural and fluid, particularly when imposing bounds and momentum. - Momentum-based animation - if you have ThrowPropsPlugin loaded, you can simply set
throwProps:truein the config object and it'll automatically apply natural, momentum-based movement after the mouse/touch is released, causing the object to glide gracefully to a stop. You can even control the amount of resistance, maximum or minimum duration, etc. - Complex snapping made easy - snap to points within a certain radius (see example), or feed in an array of values and it'll select the closest one, or implement your own custom logic in a function. Ultimate flexibility. You can have things live-snap (while dragging) or only on release (even with momentum applied, thanks to ThrowPropsPlugin)!
- Impose bounds - tell a draggable element to stay within the bounds of another DOM element (a container) as in
bounds:"#container"or define bounds as coordinates likebounds:{top:100, left:0, width:1000, height:800}or specific maximum/minimum values likebounds:{minRotation:0, maxRotation:270}. - Sense overlaps with hitTest() - see if one element is overlapping another and even set a tolerance threshold (like at least 20 pixels or 25% of either element's total surface area) using the super-flexible
Draggable.hitTest()method. Feed it a mouse event and it'll tell you if the mouse is over the element. See http://codepen.io/GreenSock/pen/GFBvn for a simple example. - Define a trigger element - maybe you want only a certain area to trigger the dragging (like the top bar of a window) - it's as simple as
trigger:"#topBar", for example. - Drag position, rotation, or scroll - lots of drag types to choose from:
"x,y"|"top,left"|"rotation"|"scroll"|"x"|"y"|"top"|"left"|"scrollTop"|"scrollLeft" - Lock movement along a certain axis - set
lockAxis:trueand Draggable will watch the direction the user starts to drag and then restrict it to that axis. Or if you only want to allow vertical or horizontal movement, that's easy too using thetype("top","y"or"scrollTop"only allow vertical movement;"x","left", or"scrollLeft"only allow horizontal movement). - Rotation honors transform origin - by default, spinnable elements will rotate around their center, but you can set
transformOriginto something else to make the pivot point be elsewhere. For example, if you callTweenLite.set(yourElement, {transformOrigin:"top left"})before dragging, it will rotate around its top left corner. Or use % or px. Whatever is set in the element's css will be honored. - Rich callback system and event dispatching - you can use any of the following callbacks:
onPress,onDragStart,onDrag,onDragEnd,onRelease,,onLockAxis, andonClick. Inside the callbacks,"this"refers to the Draggable instance itself, so you can easily access its "target" or bounds, etc. If you prefer event listeners instead, Draggable dispatches events too so you can do things likeyourDraggable.addEventListener("dragend", yourFunc); - Works great with SVG
- Even works in transformed containers! Got a Draggable inside a rotated/scaled container? No problem. No other tool handles this properly that we've seen.
- Auto-scrolling, even in multiple containers - set
autoScroll:1for normal-speed auto scrolling, orautoScroll:2would scroll twice as fast, etc. The closer you move toward the edge, the faster scrolling gets. See a demo here (added in version 0.12.0) - Sense clicks when the element moves less than 3 pixels - a common challenge is figuring out when a user is trying to click/tap an object rather than drag it, so if the mouse/touch moves less than 3 pixels from its starting position, it will be interpreted as a "click" and the onClick callback will be called (and a "click" event dispatched) without actually moving the element. You can define a different threshold using
minimumMovementconfig property, likeminimumMovement:6for 6 pixels. - All major browsers are supported including IE9+. IE8 lacks hitTest() support.
See our Codepen Draggable Collection here.
To get ThrowPropsPlugin (for the momentum-based features), join Club GreenSock today. You'll be glad you did. If not, we'll gladly issue a full refund.















