Angular Drag & Drop

@angular/cdk/drag-drop module provides you a way to easily and declaratively build drag-and-drop interfaces, with support for free dragging, sorting within lists, lists, animations, touch devices, Moving items between custom drag handles, previews, and placeholders in addition to horizontal lists and locking along the axis.

Start by importing the DragDropModule into the ngmodule where you want to use the drag-and-drop features. Now you can add the cdkDrag directive to make elements draggable. When outside a cdkDropList element, draggable elements can be moved freely around the page. You can add elements to the cdkDropList where elements can be dropped.

Basic Drag & Drop

Adding a cdkDropList around a set of cdkDrag elements groups the draggable into a reordered collection. Items will be automatically rearranged when the element is moved. Note that this will not update your data model; You can listen for the cdkDropListDropped event to update the data model after the user has finished dragging.

Drag & Drop sorting

The cdkDropList directive supports moving dragged items between connected drop zones. You can connect one or more cdkDropList instances by setting the cdkDropListConnectedTo property or by wrapping the elements in an element with the cdkDropListGroup attribute.

Drag & Drop connected sorting

Note that cdkDropListConnectedTo works both with a direct reference to another cdkDropList, or by referencing the id of another drop container:

If you have an unknown number of connected drop lists, you can use the cdkDropListGroup directive to set up the connections automatically.

Note that any new cdkDropList that is added under a group will automatically be added to all other lists.

Attaching data

You can combine some arbitrary data with both cdkDrag and cdkDropList by setting cdkDragData or cdkDropListData respectively. Events fired by both directives include this data, so you can easily identify the origin of the drag or drop interaction.

Styling

The cdkDrag and cdkDropList directives include only those styles strictly necessary for functionality. The application can then customize the elements by styling CSS classes added by the directives:

Animations

The drag-and-drop module supports animations when sorting an element inside a list and animates it from where the user dropped it to its final position. To set up your animations, you must define a transition that targets the transform property. The following classes can be used for animations:

.cdk-drag - If you add a transition to this class, it will animate as the user sorts through the list.

.cdk-drag-animating - This class is added to cdkDrag when the user has stopped dragging. If you add a transition, cdkDropList will animate the element from its drop position to last inside the cdkDropList container.

Example animations:

Customizing the drag area using a handle

By default, the user can drag the entire cdkDrag element to move it around. If you restrict the user to only using a handle element, you can add the cdkDragHandle directive to an element inside cdkDrag. Note that you can have as many cdkDragHandle elements as you want:

When a cdkDrag element is raised, a preview element will appear when it is dragged. This will, by default, be a clone of the parent element next to the user's cursor. However, this Preview can be customized by providing a custom template via *cdkDragPreview.

Using the default configuration, the custom preview will not match the size of the original dragged element because the CDK does not make assumptions about the content of the element. If you want the shape to be matched, you can pass true to the matched shape input.

Note that the cloned element will remove its id attribute to avoid multiple elements having the same id on the page. It will cause any CSS that targets the ID not to be applied.

List orientation

The cdkDropList directive assumes that lists are vertical by default, and it can be changed by setting the orientation property to `"horizontal".

Restricting movement within an element

If you want to stop the user from dragging a cdkDrag element outside of another element, you can pass a CSS selector to the cdkDragBoundary attribute. The attribute works by accepting a selector and looking up the DOM until it finds an element that matches it. If a match is found, it'll be the boundary outside which the element can't be dragged. cdkDragBoundary can also be used when cdkDrag is placed inside a cdkDropList.

Dragging Fundamentals

A drag operation starts when the end-user swipes at least 5px in any direction. It is customizable and can be changed using the dragTolerance input. Otherwise, the interaction is considered as a click, and a dragClick event is triggered.

When the dragging starts, the dragStart event is triggered. The event can be canceled by setting the cancelled property to true to prevent any actual movement.

Before any actual movement is about to be performed, the dragMove event is also triggered, containing the last and next position of the pointer. It is triggered every time a movement is detected while dragging an element around.

After the user releases the mouse/touch, the drag ghost element is removed from the DOM, and the dragEnd event will be emitted.

Due to the nature of the dragMove event, it can be triggered many times in a short period, which may cause performance issues for complex operations done when triggered.

Dragging With Ghost

The igxDrag directive can be applied to any DOM element by just adding it to its template.

HTML

The default behavior of the igxDrag directive is to leave the base element unmodified and create a ghost element when the end-user performs the drag operation.

Before the ghost is rendered on the page, a ghostCreate event is triggered containing information of the ghost element added. The event is triggered right after the dragStart event. If the dragStart is canceled, no ghost will be created, and the ghostCreate event will not trigger accordingly.

Right before the ghost is about to be removed, the ghostDestroy event will be triggered.

Customizing The Ghost

The ghost element, by default, is a copy of the base element the igxDrag is used on. It can be customized by providing a template reference to the ghostTemplate input directly.

Dragging Without Ghost

If you want to move the base element to which the igxDrag directive is applied, you can set the ghost input to false. That way, there will be no extra ghost element rendered, and if you need to apply custom styling when dragging an element, you can apply it directly to the base element.

Animations

When an element is being dragged, there are no animations applied by default.

You can apply transition animation to the igxDrag at any time, but it is advised to use it when dragging ends or the element is not currently dragged. It can be achieved by using the transitionToOrigin and the transitionTo methods.

The transitionToOrigin method, as the name suggests, animates the currently dragged element or its ghost to the start position, where the dragging began. The transitionTo method animates the element to a specific location relative to the page (i.e., pageX and pageY) or the position of a specified element. If the element is not currently dragged, it will animate or create a ghost and animate it to the desired position.

Both functions have arguments that you can set to customize the transition animation and set duration, timing function, or delay. If a specific start location is set, it will animate the element starting from there.

The transition animation will be removed if a ghost is created, and the igxDrag directive will return to its initial state. If no ghost is created, it will keep its position. In both cases, then the transitioned event will be triggered, depending on how long the animation lasts. If no animation is applied, it will be triggered instantly.

You can have other types of animations that involve element transformations. Like any other element, that can be done using the Angular Animations or straight CSS Animations to either the base igxDrag element or its ghost. If you want to apply them to the ghost, you need to define a custom ghost and apply its elements.

Ignoring draggable elements

any dragging action. This will leave these elements be fully interactable and receive all mouse events.

Drop Directive

When an element drawn using the igxDrag directive needs to be placed in an area, igxDrop can be used to achieve this behavior. It provides events that you can use to determine if an element is entering the bounds of the element it is applied to and if it is being left inside it.

The igxDrop directive can be applied to any DOM element, just like the igxDrag directive.

By default, the igxDrag directive does not apply any logic to modify the position of the dragged element in the DOM. So you need to specify dropStrategy or implement custom logic. Drop strategies are discussed in the next section.

Default - Performs no action when an element is dropped on an igxDrop element and implemented as a class called IgxDefaultDropStrategy.

Append - Always inserts the dropped element as the last child and is implemented as a class.

A strategy can be applied by setting the dropStrategy input to one of the listed classes above. The value provided must be a type and not an instant since the igxDrop needs to create and manage itself.

Example

TypeScript:

TYPESCRIPT:

Cancelling a drop strategy

When using a specific drop strategy, its behavior can be canceled in the dropped events by setting the Cancel property to true. The dropped event is specific to the igxDrop. If you do not have a drop strategy applied to the igxDrop canceling the event would have no side effects.

Example: