KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #deepseek-harness #dsh-plugin #react #windows #developer-tools

dragster

★ 102 Open GitHub ↗

Tiny vanilla JS plugin that enables drag'n'drop interactions to a user of your website

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# dragster.js

[![DragsterJS NPM version](https://badge.fury.io/js/dragsterjs.svg)](https://badge.fury.io/js/dragsterjs)

[![DragsterJS gzip size](http://img.badgesize.io/https://unpkg.com/dragsterjs/dragster.min.js?compression=gzip
)](https://unpkg.com/dragsterjs/dragster.min.js)

Tiny vanilla JS library that enables drag'n'drop interactions to a user of your website.
By implementing this library a user is able to drag'n'drop elements on user-defined drop regions.
It works both on desktop (using mouse interface) and mobile devices (using touch interface).

See the library in action at the demo page: [Dragster.js demo page](http://sunpietro.github.io/dragster/)

## Migrating to v2.0.0

**v2.0.0 is a breaking change.** The UMD/CommonJS build has been dropped. The library is now distributed as an ES6 module only.

If you are using `require('dragsterjs')` or importing via AMD/RequireJS, you will need to migrate:

```javascript
// Before (v1.x — CommonJS, no longer works)
const Dragster = require('dragsterjs');

// After (v2.x — ES6 module)
import Dragster from 'dragsterjs';
```

Browser support is **last 3 versions** of major browsers.

## How to install?
You can install this library in several ways:
* Clone this repository on Github,
* Install using npm (Node.js dependencies manager) with following command:

```
    npm install dragsterjs
    ```

* Install using Yarn:
    
    ```
    yarn add dragsterjs
    ```

## The sample usage
To start having fun with dragging elements on the website prepare the following HTML code and add few lines of CSS:

```html
<div class="dragster-region">
    <div class="dragster-block"></div>
    <div class="dragster-block"></div>
    <div class="dragster-block"></div>
</div>
```

Then add following JS code:

```javascript
var dragster = window.Dragster({
    elementSelector: '.dragster-block',
    regionSelector: '.dragster-region'
});
```

If you would like to use DragsterJS as ES6 module in the browser:

```html
<script type="module">
    import Dragster from './dragster.js';
    const dragster = Dragster();
</script>
```

These few lines of CSS are required to prevent issues while dropping the elements.

``` css
/*
 * Prevents user from selecting text
 * in the draggable elements
 */
[draggable] {
  -webkit-user-select: none;
     -moz-user-select: none;
      -ms-user-select: none;
          user-select: none;
}

/* 
 * Prevent the element currently being dragged from
 * receive pointer events, otherwise the dropping
 * zone behind it can't receive the hover mouse events.
 */
.dragster-temp {
  pointer-events: none;
}
```

If you need to further customize the look and feel of the elements being dragged or the dropping regions check the `dragster.style.css` file.

## Replace elements instead of moving them
If you want to replace elements instead of moving them between regions you can initialize Dragster.js library with an option `replaceElements: true`:

```javascript
var dragster = window.Dragster({
    elementSelector: '.dragster-block',
    regionSelector: '.dragster-region',
    replaceElements: true
});
```

## Don't update droppable regions' height
If you don't want to update regions height value when dragging and dropping element on a region you can initialize Dragster.js library with an option `updateRegionsHeight: false`:

```javascript
var dragster = window.Dragster({
    elementSelector: '.dragster-block',
    regionSelector: '.dragster-region',
    updateRegionsHeight: false
});
```

## Update draggable elements on demand
If you have an app where elements are added dynamically, you can update the draggable elements list on demand:

```javascript
var dragster = window.Dragster({
    elementSelector: '.dragster-block',
    regionSelector: '.dragster-region'
});

dragster.update();
```

## Allow cloning blocks from a selected zones
Imagine you have a shopping cart with a list of products. You want to allow dropping multiple items into the shopping cart without removing an item from the list of available shop items.

```javascript
var dragster = window.Dragster({
    elementSelector: '.dragster-block',
    regionSelector: '.dragster-region',
    dragOnlyRegionCssClass: 'dragster-region--drag-only',
    cloneElements: true
});
```

## Properties
List of properties:
### elementSelector (required) - {String}
CSS selector for all elements that should be draggable. Default value: `'.dragster-block'`
### regionSelector (required) - {String}
CSS selector for all regions where drag'n'drop is active. Default value: `'.dragster-region'`
### dragHandleCssClass - {String|Boolean}
When set to a CSS class name, drag only initiates if the mousedown target has that class. Useful for implementing drag handles (e.g. a grip icon inside a card). Default value: `false` (entire element is draggable).
### replaceElements - {Boolean}
Indicator stating if dropped element should switch position with drop target.
It takes either `true` or `false` value. Default value: `false`.
### cloneElements - {Boolean}
Indicator stating if dropped element should be cloned into the new position (original stays in place).
Requires `dragOnlyRegionCssClass` to be applied in the HTML markup. It takes either `true` or `false` value. Default value: `false`.
### updateRegionsHeight - {Boolean}
It is indicator whether regions should update their height according to the number of elements visible in the region.
It takes either `true` or `false` value. Default value: `true`.
### minimumRegionHeight - {Number}
Tell the dragster to not to resize the regions below provided value. Default value: `60`.
### scrollWindowOnDrag - {Boolean}
Tell the dragster to scroll window while dragging an element. Default value: `false`.
### dragOnlyRegionCssClass - {String}
The drag-only region CSS class name. Used to identify regions. Default value: `'dragster-region--drag-only'`.
### wrapDraggableElements - {Boolean}
By default all draggable elements are wrapped in a wrapper `<div>`, by settings this variable to `false` this behavior can be disabled. This can sometimes be useful when using the script in frameworks like Angular or such.

**IMPORTANT**

If you put this value to `false`, you **MUST** do the wrapping of the elements yourself.
A wrapper container looks like this `<div draggable="true" class="dragster-draggable"> ... </div>`
### shadowElementUnderMouse - {Boolean}
By default the shadow element is placed on half of its width, by setting this variable to `true` the shadow element will stays where user clicks on draggable element.

## Properties - callbacks
These properties allow a developer to control the behaviour of dragster.js library using callbacks.
All callbacks receive **one param — a Dragster event object** with the following shape:

```javascript
{
    drag: { node },        // the element being dragged
    drop: { node },        // the element being dropped onto
    shadow: { node, top, left }, // the shadow (ghost) element and its position
    placeholder: { node, position }, // the drop placeholder ('top' or 'bottom')
    dropped: node,         // reference to the dropped element (post-drop callbacks)
    clonedFrom: node,      // source element when cloning
    clonedTo: node         // cloned element placed in the target region
}
```

Returning `false` from `onBeforeDragStart`, `onBeforeDragMove`, or `onBeforeDragEnd` cancels the action.

### onBeforeDragStart - {Function}
Called before drag starts. Return `false` to prevent the drag.
### onAfterDragStart - {Function}
Called after drag starts.
### onBeforeDragMove - {Function}
Called before each drag move. Return `false` to prevent the drop.
### onAfterDragMove - {Function}
Called after each drag move.
### onBeforeDragEnd - {Function}
Called before drag ends. Return `false` to prevent the drop.
### onAfterDragEnd - {Function}
Called after drag ends.
### onAfterDragDrop - {Function}
Called after an element is dropped.

## Methods
List of methods ready to be used by any webdeveloper:
### update
Re-scans the DOM for draggable elements matching `elementSelector`. Call this after dynamically adding new elements to a region so they become draggable.
### updateRegions
Re-scans the DOM for regions matching `regionSelector` and re-attaches event listeners. Call this after dynamically adding new regions to the page.
### destroy
Removes all event listeners added by DragsterJS. Call this when tearing down the component to prevent memory leaks.

dragster

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README