Security News
Maven Central Adds Sigstore Signature Validation
Maven Central now validates Sigstore signatures, making it easier for developers to verify the provenance of Java packages.
By Sarah Gooding - Feb 06, 2025
New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
draggables
Draggable elements.
Basic Usage
$ npm install draggables
<!-- HTML -->
<body>
<div data-drag-role="draggable"></div>
</body>
// js / ts
import {draggables} from 'draggables';
draggables(contextElm, options);
Section Links:
- Context Element
- Boundary Element
- Data Attributes
- Instance API:
Context Element
Default - document.body
NOTE: The context element is not necessarily a draggable element.
At creation, passing an element to the draggables(ctxElm) function binds a single event listener to the passed in element. This starts listening to pointerdown events on draggable elements within that context element. If no element was passed in at creation the default context element will be the <body> element.
Many times the context element would be the immediate parent of the draggable elements, the "board" of the "stickynotes". If you have more than one "board" you can either make a single context for all off them (a mutual ancestor or the <body>) or prefer to work with multiple instances/contexts.
Things to consider:
- There's one
Draggablesinstace per context element. - Each instance/context binds its own
pointerdownevent listener. - Each context is the boundary element to its draggable elements (by default).
Boundary Element
To prevent users from dragging an element off-screen and being unable to retrieve it, a boundary element is always defined.
By default, the <body> element acts as the global movement container for all draggable elements. However, you can designate a different element as the boundary of its descendant draggable elements by adding the data-drag-zone attribute to it.
So a draggable element's dragging zone is its closest parent with the data-drag-zone attribute or the <body> element.
Data Attributes
Using different data attributes you can control the dragging behavior.
To make an element "draggable" set its
data-drag-roleattribute to"draggable".
data-drag-zone- set this attribute (key only, no value) on the element you want to define as the boundary element of its descendant draggable elements (see Boundary Element).data-drag-role="draggable" | "grip""draggable"- Makes the element draggable.
Can be used together with:-
data-drag-axis="x" | "y"
By default you can drag elements freely on both axes. You can Limit an element's movement to a single axis."x"- Limit dragging movment along thexaxis."y"- Limit dragging movment along theyaxis.
-
data-drag-disabled"true"- Disables dragging"false"- Enables dragging
Set this attribute when you need to toggle draggability of a draggable element.
This toggles draggability of a single draggable element. If you want to disable all draggables in a context see.disable()below.
-
"grip"- The element becomes the handle of its closest draggable element. When used, draggable elements can only be dragged when grabbed by their grip element. A grip must be a descendant of a draggable element (throws an error when it's not).
Example:
<div
class="card"
data-drag-role="draggable"
data-drag-axis="x"
data-drag-disabled="false"
>
<div class="card-title" data-drag-role="grip">
Grab here!
</div>
<div class="card-body">
Grab the title to move the card
</div>
</div>
"read-only" data attributes
Not actually read-only attributes per se but you probably should not change them.
data-drag-active (key only attribute)
While dragging an element it is set with a "read-only" data attribute: data-drag-active . It is removed on drop. This is mostly for styling purposes.
[data-drag-active] {
background-color: yellow;
}
data-drag-position="x,y"
Elements are moved around using CSS translate(x, y) which sets a relative position to an element's original-natural position. When dropping an element its [x,y] position is saved as value of the data-attribute data-drag-position="x,y". This position will be used as the new starting point for the following drag event.
Instance API
draggables(contextElement, options)
arguments
contextElement: HTMLElement- optional. See Context Element section above.options: DraggablesOptions- optional. The instance's configuration object, applied for all draggable elements under the context element:padding: number- Blocks dragStart if the draggable element was grabbed by its edge within this number of pixels. Default is0.cornerPadding: number- Blocks dragStart if the draggable element was grabbed by its corner within this number of pixels. Default is0.
draggables(); // --> <body>
draggables({padding: 8}); // --> <body>
draggables(myElm);
draggables(myElm, {padding: 8});
The padding options are for dealing with draggable elements that are also resizable (by grabbing their corners/edges).
Returns a Draggables instance:
const d = draggables();
It has the following methods:
.enable() / .disable()
Toggle draggability for all draggable elements within the context. When disabled, the main element gets a 'drag-disabled' classname.
const d = draggables();
// draggability is enabled on construction
d.disable();
d.enable();
Note: Calling
.disable()on an instance disables draggability for all draggable elements withing the context element. You can disable specific draggable elements using the disable data attribute. See Data Attributes.
.on(eventName, callback) / .off(eventName)
Start and stop listening to drag events:
'grab'- fires onpointerdownon a draggable element.'dragStart'- drag started, fires on the firstpointermoveon a draggable element (afterpointerdown).'dragging'- dragging around, fires on everypointermoveexcept the first one.'dragEnd'- dragging ended, fires onpointerup.
A Draggables instance can only hold a single event listener for each event (unlike an EventEmitter):
const doSomething = () => {...}
const doSomethingElse = () => {...}
const stopDoingThing = () => {...}
const d = draggables()
.on('dragStart', doSomething) // <-- this is replaced
.on('dragStart', doSomethingElse) // <-- by this (same event)
.on('dragEnd', stopDoingThing)
d.off('dragStart');
Event Handlers
The event handlers get called with a DragEventWrapper object which holds 3 properties:
ev- the vanilla pointer event (typePointerEvent)elm- the draggable element, which is not always theev.target(typeHTMLElement),relPos- the draggable element's relative position (in pixels), that is, relative to its pre-drag position (type[x: number, y: number])
draggables().on('dragging', (dragEv: DragEventWrapper) => {
console.log(
dragEv.elm, // e.g. <div data-drag-role="draggable">
dragEv.ev.target, // e.g. <div data-drag-role="grip">
dragEv.relPos // e.g. [3, -8] (on 'grab' events it's always [0,0])
);
});
.destroy()
Kills the Draggables instance for good, unbinds event listeners, releases element references. Once destroyed, an instance cannot be revived. Use it when the context element is removed from the DOM.
FAQs
Draggable elements.
We found that draggables demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Package last updated on 13 Dec 2024
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
38% of CISOs Fear They’re Not Moving Fast Enough on AI
CISOs are racing to adopt AI for cybersecurity, but hurdles in budgets and governance may leave some falling behind in the fight against cyber threats.
By Sarah Gooding - Feb 04, 2025
Research
Security News
Go Supply Chain Attack: Malicious Package Exploits Go Module Proxy Caching for Persistence
Socket researchers uncovered a backdoored typosquat of BoltDB in the Go ecosystem, exploiting Go Module Proxy caching to persist undetected for years.
By Kirill Boychenko - Feb 04, 2025