[](http://badge.fury.io/js/ng2-dragula) [](https://npmjs.org/ng2-dragula) [](https://
npm install ng2-dragula-angular13  
!Logo
> Drag and drop so simple it hurts
Official Angular wrapper for dragula.
sh
npm install ng2-dragula
or
yarn add ng2-dragula
`
Setup
$3
`ts
(window as any).global = window;
`
This is a temporary workaround for
#849, while upstream
dragula still relies on global.
$3
`typescript
import { DragulaModule } from 'ng2-dragula';
@NgModule({
imports: [
...,
DragulaModule.forRoot()
],
})
export class AppModule { }
`
On any child modules (like lazy loaded route modules), just use DragulaModule.
$3
You'll also need to add Dragula's CSS stylesheet dragula.css to your
application (e.g. in styles.scss). The following is slightly better than
node_modules/dragula/dist/dragula.css (it includes pointer-events: none
(#508) and
this fix),
but you may wish to make your own modifications.
`scss
/ in-flight clone /
.gu-mirror {
position: fixed !important;
margin: 0 !important;
z-index: 9999 !important;
opacity: 0.8;
-ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=80)";
filter: alpha(opacity=80);
pointer-events: none;
}
/ high-performance display:none; helper /
.gu-hide {
left: -9999px !important;
}
/ added to mirrorContainer (default = body) while dragging /
.gu-unselectable {
-webkit-user-select: none !important;
-moz-user-select: none !important;
-ms-user-select: none !important;
user-select: none !important;
}
/ added to the source element while its mirror is dragged /
.gu-transit {
opacity: 0.2;
-ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=20)";
filter: alpha(opacity=20);
}
`
$3
Here's a super quick sample to get you started:
`typescript
@Component({
selector: "sample",
template:
})
class Sample {}
`
Usage
This package isn't very different from dragula itself. I'll mark the
differences here, but please refer to the documentation for
dragula if you need to learn more about
dragula itself.
Directive
There's a dragula directive that makes a container's direct children
draggable. You must supply a string. Both syntaxes, dragula="VAMPIRES" or
[dragula]="'VAMPIRES'", work equally well.
`html
- Dracula
- Kurz
- Vladislav
- Deacon
`
Grouping containers
You can group containers together by giving them the same group name. When you
do, the children of each container can be dragged to any container in the same
group.
`html
`
If you want to make sure you are using the same type string in different places,
use the [dragula] syntax to pass a string variable from your component:
`html
`
`ts
class MyComponent {
Vampires = "VAMPIRES";
}
`
Saving changes to arrays with
[(dragulaModel)]
If your container's children are rendered using ngFor, you may wish to read what your users have done. If you provide the same array to the [(dragulaModel)] attribute on the container element, any changes will be synced back to the array.
NOTE: v2 changes the behaviour of [dragulaModel]. It no longer mutates the arrays you give it, but will shallow clone them and give you the results. Use two-way binding with [(dragulaModel)]="...", or use the DragulaService dropModel and removeModel events to save the new models produced.
`html
-
{{ vamp.name }} likes {{ vamp.favouriteColor }}
`
You do not, of course, have to sync the changes back. The [(dragulaModel)] syntax is equivalent to:
`html
...
`
Note: DO NOT put any other elements inside the container. The library relies
on having the index of a DOM element inside a container mapping directly to
their associated items in the array. Everything will be messed up if you do
this.
On top of the normal Dragula events, when [(dragulaModel)] is provided, there are two extra events: dropModel and removeModel. Further details are available under Events
Drake options
If you need to configure the drake _(there's exactly one drake per group)_, you can use the DragulaService.
`ts
import { DragulaService } from 'ng2-dragula';
class ConfigExample {
constructor(private dragulaService: DragulaService) {
dragulaService.createGroup("VAMPIRES", {
removeOnSpill: true
});
}
}
`
See below for more info on options.
DragulaService
This service exposes a few different methods with which you can interact with dragula.
$3
NOTE: formerly known as setOptions()
Creates a group named name, with an
options object.
$3
Returns a Group named name, if there is one. A Group contains the following
properties.
- name is the name that identifies the group
- drake is the raw drake instance itself
- options is the options object used to create the drake. Modifying it won't
do anything useful.
$3
Destroys a Group named name and its associated drake instance. Silently
returns if the group does not exist.
$3
Refer to the documentation for
dragula to learn more about the
native options.
All of the native options work with ng2-dragula. However, there is one addition:
#### copyItem:
When you have:
* [(dragulaModel)]
copy is true or a function that returns true*
... ng2-dragula will have to create a clone of the JS object you picked up. In
previous versions of ng2-dragula, there was a terribly buggy,
one-size-fits-all clone function. From v2 onwards, you MUST provide your own
copyItem function.
If you have a simple object with no nested values, it could be as simple as:
`ts
{
copy: ...,
copyItem: (item: MyType) => ({ ...item })
}
`
There is a complete example using a Person class on the demo page.
Events
Whenever a drake instance is created with the dragula directive, there are
several events you can subscribe to via DragulaService. Each event emits
a typed object, which you can use to get information about what happened.
Refer to the Drake events
documentation for more
information about the different events available. Each event follows this
format:
`yml
Event named: 'drag'
Native dragula:
Use: drake.on('drag', listener)
Listener arguments: (el, source)
ng2-dragula:
Method: DragulaService.drag(groupName?: string): Observable<...>
Observable of: { name: string; el: Element; source: Element; }
`
Each supports an optional parameter, groupName?: string, which filters events
to the group you're interested in. This is usually better than getting all
groups in one observable.
The sample below illustrates how you can use destructuring to pull values from
the event, and unsubscribe when your component is destroyed.
`html
`
`ts
import { Subscription } from 'rxjs';
import { DragulaService } from 'ng2-dragula';
export class MyComponent {
// RxJS Subscription is an excellent API for managing many unsubscribe calls.
// See note below about unsubscribing.
subs = new Subscription();
constructor(private dragulaService: DragulaService) {
// These will get events limited to the VAMPIRES group.
this.subs.add(this.dragulaService.drag("VAMPIRES")
.subscribe(({ name, el, source }) => {
// ...
})
);
this.subs.add(this.dragulaService.drop("VAMPIRES")
.subscribe(({ name, el, target, source, sibling }) => {
// ...
})
);
// some events have lots of properties, just pick the ones you need
this.subs.add(this.dragulaService.dropModel("VAMPIRES")
// WHOA
// .subscribe(({ name, el, target, source, sibling, sourceModel, targetModel, item }) => {
.subscribe(({ sourceModel, targetModel, item }) => {
// ...
})
);
// You can also get all events, not limited to a particular group
this.subs.add(this.dragulaService.drop()
.subscribe(({ name, el, target, source, sibling }) => {
// ...
})
);
}
ngOnDestroy() {
// destroy all the subscriptions at once
this.subs.unsubscribe();
}
}
`
NOTE: You should always unsubscribe each time you listen to an event. This
is especially true for a component, which should tear itself down completely in
ngOnDestroy, including any subscriptions. It might not be necessary if you
have a global singleton service (which is never destroyed) doing the
subscribing.
You can also engineer your use of events to avoid subscribing in the first
place:
`ts
import { merge } from 'rxjs';
import { mapTo, startWith } from 'rxjs/operators';
dragStart$ = this.dragulaService.drag("VAMPIRES").pipe(mapTo(true));
dragEnd$ = this.dragulaService.dragend("VAMPIRES").pipe(mapTo(false));
isDragging$ = merge(dragStart$, dragEnd$).pipe(startWith(false));
// html: [class.dragging]="isDragging$ | async"
`
Special Events for
ng2-dragula
The dropModel(name?: string) and removeModel(name?: string) events are only active when you have supplied [dragulaModel].
| Event Name | Listener Arguments | Event Description |
| :-------------- | :-------------------------: | :--------------------------------------------------------------------------------------- |
| dropModel | { type, el, target, source, item, sourceModel, targetModel, sourceIndex, targetIndex } | same as normal drop, but with updated models + the item that was dropped |
| removeModel | { type, el, container, source, item, sourceModel, sourceIndex } | same as normal remove, but with updated model + the item that got removed |
Classic Blunders
There are a number of very common issues filed against this repo. You will be
mocked terribly if you file a bug and it turns out you made one of these
blunders and it wasn't a bug at all.
$3
WRONG:
`html
dragula="WRONG" [(dragulaModel)]="list">...
RIGHT:
`html
...
`
$3
WRONG:
`html
WRONG: This header will mess up everything, and you will
get really weird bugs on drop
...
`
RIGHT:
`html
This header will not be draggable or affect drags at all.
...
`
Alternatives
There are hundreds of other libraries that do this. Some notable ones:
- @angular-skyhook, specifically with the sortable. Also by me (@cormacrelf).
- @angular/cdk/drag-drop -- no documentation yet, but will presumably be well-supported.
Development
- You must use Yarn >= 1.3. It includes the 'workspaces' feature.
- Please use Conventional Commits in your commit messages.
#### setup
`sh
yarn
yarn workspace ng2-dragula build
`
#### run tests
`sh
yarn workspace ng2-dragula test
or
yarn workspace ng2-dragula test:headless
`
#### run demo server
`sh
listens for changes in the library and rebuilds on save
yarn watch
runs demo server
yarn workspace demo start
`
#### Publishing a new version
`
yarn lerna publish
`
Credits
- v1: Nathan Walker (@NathanWalker)
- v1.x: Dmitriy Shekhovtsov (@valorkin)
- v2`: Cormac Relf (@cormacrelf)