neodragvanillaboundspatch
Advanced tools
A lightweight vanilla JS(plain JS) library to make your elements draggable.
Inspired from the amazing react-draggable library, and implements a similar API, but 3x smaller.
pnpm add @neodrag/vanilla
# npm
npm install @neodrag/vanilla
# yarn
yarn add @neodrag/vanilla
Basic usage
import { Draggable } from '@neodrag/vanilla';
const dragInstance = new Draggable(document.querySelector('#drag'));
With options
import { Draggable } from '@neodrag/vanilla';
const dragInstance = new Draggable(document.querySelector('#drag'), {
axis: 'x',
grid: [10, 10],
});
Defining options elsewhere with typescript
import { Draggable } from '@neodrag/vanilla';
const options: DragOptions = {
axis: 'y',
bounds: 'parent',
};
const dragInstance = new Draggable(document.querySelector('#drag'), options);
Update options:
import { Draggable } from '@neodrag/vanilla';
const dragInstance = new Draggable(document.querySelector('#drag'), {
axis: 'x',
grid: [10, 10],
});
// Update the specific options. Will be merged with the existing options.
dragInstance.update({
axis: 'y',
});
// Completely overrides existing options, in this case, the `grid` property is removed
dragInstance.options = {
axis: 'y',
};
There are tons of options available for this package. All of them are already documented within the code itself, so you'll never have to leave the code editor.
type: 'both' | 'x' | 'y' | 'none'
Default Value: 'both'
Axis on which the element can be dragged on. Valid values: both, x, y, none.
both - Element can move in any directionx - Only horizontal movement possibley - Only vertical movement possiblenone - No movement at allExamples:
// Drag only in x direction
new Draggable(el, { axis: 'x' });
type: HTMLElement | 'parent' | string | { top?: number; right?: number; bottom?: number; left?: number }
Default Value: undefined
Optionally limit the drag area
parent: Limit to parent
Or, you can specify any selector and it will be bound to that.
Note: This library doesn't check whether the selector is bigger than the node element. You yourself will have to make sure of that, or it may lead to unexpected behavior.
Or, finally, you can pass an object of type { top: number; right: number; bottom: number; left: number }.
These mimic the css top, right, bottom and left, in the sense that bottom starts from the bottom of the window, and right from right of window.
If any of these properties are unspecified, they are assumed to be 0.
Examples:
Bound to any element
new Draggable(el, { bounds: document.querySelector('.some-element') });
Bound to parent
new Draggable(el, { bounds: 'parent' });
Bound to body
new Draggable(el, { bounds: 'body' });
Bound to an ancestor selector somewhere in page
new Draggable(el, { bounds: '.way-up-in-the-dom' });
Manually through coordinates. Empty object means bound to the window.
NOTE: It isn't strictly empty object. If you omit any property from this object, it will be assumed as 0.
new Draggable(el, { bounds: {} });
Bound only to top and bottom, and unbounded horizontally in practice by setting bounds way beyond the screen.
new Draggable(el, { bounds: { top: 0, bottom: 0, left: -1000, right: -1000 } });
type: boolean
Default value: true
If true, uses translate3d instead of translate to move the element around, and the hardware acceleration kicks in.
true by default, but can be set to false if blurry text issue occurs.
Example 👇
new Draggable(el, { gpuAcceleration: false });
type: boolean
Default value: true
Applies user-select: none on <body /> element when dragging, to prevent the irritating effect where dragging doesn't happen and the text is selected. Applied when dragging starts and removed when it stops.
new Draggable(el, { applyUserSelectHack: false });
type: boolean
Default value: false
Ignores touch events with more than 1 touch. This helps when you have multiple elements on a canvas where you want to implement pinch-to-zoom behaviour.
new Draggable(el, { ignoreMultitouch: true });
type: boolean
Default Value: undefined
Disables dragging.
type: [number, number]
Default value: undefined
Applies a grid on the page to which the element snaps to when dragging, rather than the default continuous grid.
Note: If you're programmatically creating the grid, do not set it to [0, 0] ever, that will stop drag at all. Set it to undefined to make it continuous once again.
type: { x: number; y: number }
Default Value: undefined
Controls the position of the element programmatically. Fully reactive.
Read more below in the Controlled vs Uncontrolled section.
type: string | HTMLElement | HTMLElement[]
Default value: undefined
CSS Selector of an element or multiple elements inside the parent node(on which Draggable is applied). Can be an element or elements too. If it is provided, Trying to drag inside the cancel element(s) will prevent dragging.
Selector(Selects multiple too using el.querySelectorAll):
new Draggable(el, { cancel: '.cancel' });
Element:
new Draggable(el, { cancel: [el.querySelector('.cancel')] });
for this element structure:
<div class="draggable">
I can be dragged
<div class="cancel">I won't allow dragging</div>
</div>
Multiple Elements:
new Draggable(el, {
cancel: [el.querySelector('.cancel1'), el.querySelector('.cancel2')],
});
With html structure
<div>
This will drag!
<div class="cancel">Cancel me out</div>
<div class="cancel">Cancel me out pt 2</div>
</div>
type: string | HTMLElement | HTMLElement[]
Default Value: undefined
CSS Selector of an element or multiple elements inside the parent node(on which Draggable is applied). Can be an element or elements too. If it is provided, Only clicking and dragging on this element will allow the parent to drag, anywhere else on the parent won't work.
Element:
new Draggable(el, { handle: '.handle' });
HTML structure:
<div>
You shall not drag!!🧙♂️
<div class="handle">This will drag 😁</div>
</div>
Multiple handles with selector:
new Draggable(el, { handle: '.handle' });
<div>
You shall not drag!!🧙♂️
<div class="handle">This will allow drag 😁</div>
<div class="handle">This will allow drag too 😁</div>
<div class="handle">This will allow drag three 😁</div>
</div>
Handle with element:
new Draggable(el, { cancel: [el.querySelector('.cancel')] });
<div>
You shall not drag!!🧙♂️
<div class="handle">This will drag 😁</div>
</div>
Multiple handles with elements
const handle1 = document.querySelector('.handle1');
const handle2 = document.querySelector('.handle2');
const handle3 = document.querySelector('.handle3');
new Draggable(el, { handle: [handle1, handle2, handle3] });
<div>
You shall not drag!!🧙♂️
<div class="handle1">This will allow drag 😁</div>
<div class="handle2">This will allow drag too 😁</div>
<div class="handle3">This will allow drag three 😁</div>
</div>
type: string
Default Value: 'neodrag'
Class to apply on the element on which new Draggable is applied.
Note that if handle is provided, it will still apply class on the parent element, NOT the handle
type: string
Default Value: 'neodrag-dragging'
Class to apply on the parent element when it is dragging
type: string
Default Value: 'neodrag-dragged'
Class to apply on the parent element if it has been dragged at least once.
type: { x: number; y: number }
Default Value: { x: 0, y: 0 }
Offsets your element to the position you specify in the very beginning. x and y should be in pixels
type: (data: DragEventData) => void
Default Value: undefined
Fires when dragging start.
Note:
type DragEventData = { offsetX: number; offsetY: number; domRect: DOMRect };
type: (data: DragEventData) => void
Default Value: undefined
Fires when dragging is going on.
Note:
type DragEventData = { offsetX: number; offsetY: number; domRect: DOMRect };
type: (data: DragEventData) => void
Default Value: undefined
Fires when dragging ends.
Note:
type DragEventData = { offsetX: number; offsetY: number; domRect: DOMRect };
@neodrag/vanilla emits 3 events, onDrag, onDragStart & onDragEnd.
Example:
new Draggable({
onDragStart: (data) => console.log('Dragging started', data),
onDrag: (data) => console.log('Dragging', data),
onDragEnd: (data) => console.log('Dragging stopped', data),
});
This library ships with proper TypeScript typings, for the best Developer Experience, whether authoring JS or TS.
This package exports these types you can use:
import type {
DragAxis,
DragBounds,
DragBoundsCoords,
DragOptions,
DragEventData,
} from '@neodrag/solid';
DragOptions is the documented list of all options provided by the component.
DragAxis is the type of axis option, and is equal to 'both' | 'x' | 'y' | 'none'.
DragBounds is 'parent' | string | Partial<DragBoundsCoords>, the complete type of bounds option.
DragBoundsCoords is when you're specifying the bounds field using an object, this is the type needed for that.
export type DragBoundsCoords = {
/** Number of pixels from left of the window */
left: number;
/** Number of pixels from top of the window */
top: number;
/** Number of pixels from the right side of window */
right: number;
/** Number of pixels from the bottom of the window */
bottom: number;
};
type DragEventData = {
offsetX: number;
offsetY: number;
domRect: DOMRect;
};
This is taken straight from React's philosophy(After all, this package is inspired from react-draggable).
Uncontrolled means your app doesn't control the dragging of the app. Meaning, the user drags the element, it changes position, and you do something with that action. You yourself don't change position of the element or anything. This is the default behavior of this library.
Controlled means your app, using state variables, changes the position of the element, or in simple terms, programmatically drag the element. You basically set the position property to { x: 10, y: 50 }(or any other numbers), and voila! yur now controlling the position of the element programmatically 🥳🥳
OFC, this library doesn't go fully Controlled. The user can still drag it around even when position is set.
So, when you change position, the element position changes. However, when the element is dragged by user interaction, position is not changed. This is done intentionally, as two-way data binding here isn't possible and also will lead to unexpected behavior. To keep the position variable up to date, use the onDrag event to keep your state up to date to the draggable's internal state.
To have it be strictly Controlled, meaning it can only be moved programmatically, add the disabled option to your draggable element's config
new Draggable({ position: { x: 0, y: 10 }, disabled: true });
Here are a bunch of examples showing controlled behavior 👇
Feel free to open an issue with a bug or feature request.
If you wish to make a PR fixing something, please open an issue about it first!
This library lacks something very important: Automated Tests!
I'll be straight about this: I don't know how to write tests. I've tried, but not been able to.
So I need your help. If you wish to contribute and can add tests here, it would be great for everyone using this! 🙂. There are already some tests but it could benefit from more test cases
Specifications here: #7
MIT License © Puru Vijay
FAQs
JS library to add dragging to your apps 😉
The npm package neodragvanillaboundspatch receives a total of 1 weekly downloads. As such, neodragvanillaboundspatch popularity was classified as not popular.
We found that neodragvanillaboundspatch demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
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.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.