node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »

drag-drop-webkit-mobile

iOS shim for HTML 5 drag'n'drop

The HTML 5 drag'n'drop API allows you to implement drag'n'drop with the same code on most desktop browsers. Unfortunately, you'll notice iOS doesn't support it, so no iPad (or Android) action for you!

Luckily, WebKit gives us enough tools to shim seamlessly. If you drop this script in your page your existing HTML 5 drag'n'drop code should just work.

Demos

Check out the demo to see it in action. It also works on Android.

Install/config

If you want enter/over/leave events, add a config object to the page before you include the shim.

<script>
var iosDragDropShim = { enableEnterLeave: true }
</script> 
<script src="vendor/ios-drag-drop.js"></script>

If you want to the user to hold to drag, add a config object to the page before you include the shim.

<script>
var iosDragDropShim = { holdToDrag: 300 } //Adds 300ms delay before draging
</script> 
<script src="vendor/ios-drag-drop.js"></script>

By default the shim will simulate a mouseclick when a user touches an anchor. See here for more details. Sometimes we want to disable that functionality since it can lead to unintended clicks during a scroll, and you may have other libraries in place to ensure the appropriate response. You can do that by setting the 'simulateAnchorClick' option to 'false'.

<script>
var iosDragDropShim = { simulateAnchorClick: false }
</script> 
<script src="vendor/ios-drag-drop.js"></script>

To match the HTML5 and and drop spec, links and images are implicitly treated as draggable. You can turn off this behavior by setting 'requireExplicitDraggable' to 'true'. This way, only elements with the draggable attribute set to true will be draggable.

<script>
var iosDragDropShim = { requireExplicitDraggable: true }
</script> 
<script src="vendor/ios-drag-drop.js"></script>

With npm:

npm install --save drag-drop-webkit-mobile
var iosDragDropShim = require('drag-drop-webkit-mobile');
// options are optional ;) 
iosDragDropShim(options);

Known issues

iOS10 introduced a regression on touchmove handling where event.preventDefault() is not respected.

If you run into a situation where dragging and scrolling occur simultaneously apply the fix mentioned in #77.

Shim behaviour

  • all drag events, with dragenter, dragover and dragleave enabled via config flag
  • creates a partially transparent drag image based on the dragged element

Thanks

To the amazing contributors who've provided massive extensions and fixes to the original.

@rem - who created the original demo used to demo this shim's drop-in nature.

License

MIT License