@progress/kendo-draggable
v3.1.0
Published
A cross-browser/event abstraction that handles mouse and touch drag sequences
Downloads
338,432
Readme
Kendo UI Draggable
A repository for the cross-platform abstraction for drag sequences.
- Overview
- Installation
- Basic Usage
- Features
- What's Next
- Dragging on iOS/Android
- Preventing Selection
- Browser Support
Overview
The Kendo UI Draggable component handles mouse drags and touch sequences on mobile devices.
A drag sequence means:
- Mouse click, drag, release for desktop devices.
- Touch press, drag, release for mobile devices.
Installation
The library is published as a scoped NPM package in the NPMJS Telerik account.
npm install --save '@progress/kendo-draggable';
Basic Usage
The draggable
class constructor accepts an object with three optional event handler callbacks—press
, drag
, and release
.
import Draggable from '@progress/kendo-draggable';
const draggable = new Draggable({
press: function(e) {
console.log("pressed", e.pageX, e.pageY);
},
drag: function(e) {
console.log("drag", e.pageX, e.pageY);
},
release: function(e) {
console.log("release", e.pageX, e.pageY);
}
});
draggable.bindTo(document.getElementById("my-element"));
The Draggable may be re-bound to another element—the event handlers will be automatically unbound from the previous one.
draggable.bindTo(document.getElementById("another-element"));
The draggable
object persists a reference to the currently bound element. That is why it should be destroyed when or if the corresponding element is removed from the document.
draggable.destroy();
Features
The Kendo UI Draggable supports:
- Mouse events
- Touch events
- Pointer events
- Handling of multiple touches. Rather, not getting confused by them.
Dragging on iOS/Android
Handling the drag sequence on mobile devices may require the disabling of the touch-based scrolling. The Draggable will not do that out of the box. The recommended way to handle this issue is by setting a touch-action
CSS property. Depending on the type of drags that are handled, you may need touch-action: none
, touch-action: pan-y
, or touch-action: pan-x
.
The
touch-action
setting does not work for iOS yet. While the iOS 9.3 version, which has been released recently, provides limited support,pan-x
andpan-y
do not work. To disable the touch-based scrolling in iOS, prevent thetouchstart
event:
<div ontouchstart="return false">
<div id="my-draggable-element"></div>
</div>
Preventing Selection
The dragging of elements that contain text activates the browser text selection, which, in most cases, is not desirable. To avoid this behavior, use the user-select: none
CSS property with its respective browser prefixes.
Mouse-Only mode
To ignore all touch and pointer events, set mouseOnly
to true
. This is useful when you want to keep the default touch-drag behavior, e.g. horizontal scroll.
import Draggable from '@progress/kendo-draggable';
const draggable = new Draggable({
mouseOnly: true,
press: function(e) {
console.log("pressed", e.pageX, e.pageY);
},
drag: function(e) {
console.log("drag", e.pageX, e.pageY);
},
release: function(e) {
console.log("release", e.pageX, e.pageY);
}
});
draggable.bindTo(document.getElementById("my-element"));
Browser Support
- Google Chrome
- Firefox
- Safari (OS X)
- Safari (iOS)
- Chrome (Android)
- IE/Edge