API reference for Angular CDK drag-drop
import {DragDropModule} from '@angular/cdk/drag-drop';
Services
DragDrop
Service that allows for drag-and-drop functionality to be attached to DOM elements.
Methods
createDrag | |
---|---|
Turns an element into a draggable item. |
|
Parameters | |
element HTMLElement | ElementRef<HTMLElement>
|
Element to which to attach the dragging functionality. |
config DragRefConfig = DEFAULT_CONFIG
|
Object used to configure the dragging behavior. |
Returns | |
DragRef<T>
|
|
createDropList | |
---|---|
Turns an element into a drop list. |
|
Parameters | |
element HTMLElement | ElementRef<HTMLElement>
|
Element to which to attach the drop list functionality. |
Returns | |
DropListRef<T>
|
|
Directives
CdkDropList
Container that wraps a set of draggable items.
Selector: [cdkDropList] cdk-drop-list
Exported as: cdkDropListProperties
Name | Description |
---|---|
@Input({ alias: 'cdkDropListAutoScrollDisabled', transform: booleanAttribute })
|
Whether to auto-scroll the view when the user moves their pointer close to the edges. |
@Input('cdkDropListAutoScrollStep')
|
Number of pixels to scroll for each frame when auto-scrolling an element. |
@Input('cdkDropListConnectedTo')
|
Other draggable containers that this container is connected to and into which the container's items can be transferred. Can either be references to other drop containers, or their unique IDs. |
@Input('cdkDropListData')
|
Arbitrary data to attach to this container. |
@Input({ alias: 'cdkDropListDisabled', transform: booleanAttribute })
|
Whether starting a dragging sequence from this container is disabled. |
@Input('cdkDropListElementContainer')
|
Selector that will be used to resolve an alternate element container for the drop list. Passing an alternate container is useful for the cases where one might not have control over the parent node of the draggable items within the list (e.g. due to content projection). This allows for usages like:
|
@Input('cdkDropListEnterPredicate')
|
Function that is used to determine whether an item is allowed to be moved into a drop container. |
@Input()
|
Unique ID for the drop zone. Can be used as a reference
in the |
@Input('cdkDropListLockAxis')
|
Locks the position of the draggable elements inside the container along the specified axis. |
@Input('cdkDropListOrientation')
|
Direction in which the list is oriented. |
@Input('cdkDropListSortPredicate')
|
Functions that is used to determine whether an item can be sorted into a particular index. |
@Input({ alias: 'cdkDropListSortingDisabled', transform: booleanAttribute })
|
Whether sorting within this drop list is disabled. |
@Output('cdkDropListDropped')
|
Emits when the user drops an item inside the container. |
@Output('cdkDropListEntered')
|
Emits when the user has moved a new drag item into this container. |
@Output('cdkDropListExited')
|
Emits when the user removes an item from the container by dragging it into another container. |
@Output('cdkDropListSorted')
|
Emits as the user is swapping items while actively dragging. |
|
Methods
addItem | |
---|---|
Registers an items with the drop list. |
|
Parameters | |
item CdkDrag<any>
|
|
getSortedItems | |
---|---|
Gets the registered items in the list, sorted by their position in the DOM. |
|
Returns | |
CdkDrag[]
|
|
removeItem | |
---|---|
Removes an item from the drop list. |
|
Parameters | |
item CdkDrag<any>
|
|
CdkDropListGroup
Declaratively connects sibling cdkDropList
instances together. All of the cdkDropList
elements that are placed inside a cdkDropListGroup
will be connected to each other
automatically. Can be used as an alternative to the cdkDropListConnectedTo
input
from cdkDropList
.
Selector: [cdkDropListGroup]
Exported as: cdkDropListGroupProperties
Name | Description |
---|---|
@Input({ alias: 'cdkDropListGroupDisabled', transform: booleanAttribute })
|
Whether starting a dragging sequence from inside this group is disabled. |
CdkDrag
Element that can be moved inside a CdkDropList container.
Selector: [cdkDrag]
Exported as: cdkDragProperties
Name | Description |
---|---|
@Input('cdkDragBoundary')
|
Node or selector that will be used to determine the element to which the draggable's position will be constrained. If a string is passed in, it'll be used as a selector that will be matched starting from the element's parent and going up the DOM until a match has been found. |
@Input('cdkDragConstrainPosition')
|
Function that can be used to customize the logic of how the position of the drag item is limited while it's being dragged. Gets called with a point containing the current position of the user's pointer on the page, a reference to the item being dragged and its dimensions. Should return a point describing where the item should be rendered. |
@Input('cdkDragData')
|
Arbitrary data to attach to this drag instance. |
@Input({ alias: 'cdkDragDisabled', transform: booleanAttribute })
|
Whether starting to drag this element is disabled. |
@Input('cdkDragStartDelay')
|
Amount of milliseconds to wait after the user has put their pointer down before starting to drag the element. |
@Input('cdkDragFreeDragPosition')
|
Sets the position of a |
@Input('cdkDragLockAxis')
|
Locks the position of the dragged element along the specified axis. |
@Input('cdkDragPreviewClass')
|
Class to be added to the preview element. |
@Input('cdkDragPreviewContainer')
|
Configures the place into which the preview of the item will be inserted. Can be configured
globally through
|
@Input('cdkDragRootElement')
|
Selector that will be used to determine the root draggable element, starting from
the |
@Input({ alias: 'cdkDragScale', transform: numberAttribute })
|
If the parent of the dragged element has a |
@Output('cdkDragDropped')
|
Emits when the user drops the item inside a container. |
@Output('cdkDragEnded')
|
Emits when the user stops dragging an item in the container. |
@Output('cdkDragEntered')
|
Emits when the user has moved the item into a new container. |
@Output('cdkDragExited')
|
Emits when the user removes the item its container by dragging it into another container. |
@Output('cdkDragMoved')
|
Emits as the user is dragging the item. Use with caution, because this event will fire for every pixel that the user has dragged. |
@Output('cdkDragReleased')
|
Emits when the user has released a drag item, before any animations have started. |
@Output('cdkDragStarted')
|
Emits when the user starts dragging the item. |
|
|
|
Methods
getFreeDragPosition | |
---|---|
Gets the pixel coordinates of the draggable outside of a drop container. |
|
Returns | |
Readonly<Point>
|
|
getPlaceholderElement | |
---|---|
Returns the element that is being used as a placeholder while the current element is being dragged. |
|
Returns | |
HTMLElement
|
|
getRootElement | |
---|---|
Returns the root draggable element. |
|
Returns | |
HTMLElement
|
|
reset | |
---|---|
Resets a standalone drag item to its initial position. |
setFreeDragPosition | |
---|---|
Sets the current position in pixels the draggable outside of a drop container. |
|
Parameters | |
value Point
|
New position to be set. |
CdkDragHandle
Handle that can be used to drag a CdkDrag instance.
Selector: [cdkDragHandle]
Properties
Name | Description |
---|---|
@Input({ alias: 'cdkDragHandleDisabled', transform: booleanAttribute })
|
Whether starting to drag through this handle is disabled. |
|
CdkDragPreview
Element that will be used as a template for the preview of a CdkDrag when it is being dragged.
Selector: ng-template[cdkDragPreview]
Properties
Name | Description |
---|---|
@Input()
|
Context data to be added to the preview template instance. |
@Input({ transform: booleanAttribute })
|
Whether the preview should preserve the same size as the item that is being dragged. |
|
CdkDragPlaceholder
Element that will be used as a template for the placeholder of a CdkDrag when it is being dragged. The placeholder is displayed in place of the element being dragged.
Selector: ng-template[cdkDragPlaceholder]
Properties
Name | Description |
---|---|
@Input()
|
Context data to be added to the placeholder template instance. |
|
Classes
DragRef
Reference to a draggable item. Used to manipulate or dispose of the item.
Properties
Name | Description |
---|---|
|
Emits as the drag sequence is being prepared. |
|
Function that can be used to customize the logic of how the position of the drag item is limited while it's being dragged. Gets called with a point containing the current position of the user's pointer on the page, a reference to the item being dragged and its dimensions. Should return a point describing where the item should be rendered. |
|
Arbitrary data that can be attached to the drag item. |
|
Whether starting to drag this element is disabled. |
|
Amount of milliseconds to wait after the user has put their pointer down before starting to drag the element. |
|
Emits when the user drops the item inside a container. |
|
Emits when the user stops dragging an item in the container. |
|
Emits when the user has moved the item into a new container. |
|
Emits when the user removes the item its container by dragging it into another container. |
|
Axis along which dragging is locked. |
|
Emits as the user is dragging the item. Use with caution, because this event will fire for every pixel that the user has dragged. |
|
Class to be added to the preview element. |
|
Emits when the user has released a drag item, before any animations have started. |
|
If the parent of the dragged element has a |
|
Emits when the user starts dragging the item. |
Methods
disableHandle | |
---|---|
Sets a handle as disabled. While a handle is disabled, it'll capture and interrupt dragging. |
|
Parameters | |
handle HTMLElement
|
Handle element that should be disabled. |
dispose | |
---|---|
Removes the dragging functionality from the DOM element. |
enableHandle | |
---|---|
Enables a handle, if it has been disabled. |
|
Parameters | |
handle HTMLElement
|
Handle element to be enabled. |
getFreeDragPosition | |
---|---|
Gets the current position in pixels the draggable outside of a drop container. |
|
Returns | |
Readonly<Point>
|
|
getPlaceholderElement | |
---|---|
Returns the element that is being used as a placeholder while the current element is being dragged. |
|
Returns | |
HTMLElement
|
|
getRootElement | |
---|---|
Returns the root draggable element. |
|
Returns | |
HTMLElement
|
|
getVisibleElement | |
---|---|
Gets the currently-visible element that represents the drag item. While dragging this is the placeholder, otherwise it's the root element. |
|
Returns | |
HTMLElement
|
|
isDragging | |
---|---|
Checks whether the element is currently being dragged. |
|
Returns | |
boolean
|
|
reset | |
---|---|
Resets a standalone drag item to its initial position. |
setFreeDragPosition | |
---|---|
Sets the current position in pixels the draggable outside of a drop container. |
|
Parameters | |
value Point
|
New position to be set. |
Returns | |
this
|
|
withBoundaryElement | |
---|---|
Element to which the draggable's position will be constrained. |
|
Parameters | |
boundaryElement HTMLElement | ElementRef<HTMLElement>
|
|
Returns | |
this
|
|
withDirection | |
---|---|
Sets the layout direction of the draggable item. |
|
Parameters | |
direction Direction
|
|
Returns | |
this
|
|
withHandles | |
---|---|
Registers the handles that can be used to drag the element. |
|
Parameters | |
handles (HTMLElement | ElementRef<HTMLElement>)[]
|
|
Returns | |
this
|
|
withParent | |
---|---|
Sets the parent ref that the ref is nested in. |
|
Parameters | |
parent DragRef<unknown>
|
|
Returns | |
this
|
|
withPlaceholderTemplate | |
---|---|
Registers the template that should be used for the drag placeholder. |
|
Parameters | |
template DragHelperTemplate<any>
|
Template that from which to stamp out the placeholder. |
Returns | |
this
|
|
withPreviewContainer | |
---|---|
Sets the container into which to insert the preview element. |
|
Parameters | |
value PreviewContainer
|
Container into which to insert the preview. |
Returns | |
this
|
|
withPreviewTemplate | |
---|---|
Registers the template that should be used for the drag preview. |
|
Parameters | |
template DragPreviewTemplate<any>
|
Template that from which to stamp out the preview. |
Returns | |
this
|
|
withRootElement | |
---|---|
Sets an alternate drag root element. The root element is the element that will be moved as the user is dragging. Passing an alternate root element is useful when trying to enable dragging on an element that you might not have access to. |
|
Parameters | |
rootElement HTMLElement | ElementRef<HTMLElement>
|
|
Returns | |
this
|
|
DropListRef
Reference to a drop list. Used to manipulate or dispose of the container.
Properties
Name | Description |
---|---|
|
Whether auto-scrolling the view when the user moves their pointer close to the edges is disabled. |
|
Number of pixels to scroll for each frame when auto-scrolling an element. |
|
Emits right before dragging has started. |
|
Arbitrary data that can be attached to the drop list. |
|
Whether starting a dragging sequence from this container is disabled. |
|
Emits when the user drops an item inside the container. |
|
Element that the drop list is attached to. |
|
Function that is used to determine whether an item is allowed to be moved into a drop container. |
|
Emits when the user has moved a new drag item into this container. |
|
Emits when the user removes an item from the container by dragging it into another container. |
|
Locks the position of the draggable elements inside the container along the specified axis. |
|
Emits when a dragging sequence is started in a list connected to the current one. |
|
Emits when a dragging sequence is stopped from a list connected to the current one. |
|
Function that is used to determine whether an item can be sorted into a particular index. |
|
Emits as the user is swapping items while actively dragging. |
|
Whether sorting items within the list is disabled. |
Methods
connectedTo | |
---|---|
Sets the containers that are connected to this one. When two or more containers are connected, the user will be allowed to transfer items between them. |
|
Parameters | |
connectedTo DropListRef<any>[]
|
Other containers that the current containers should be connected to. |
Returns | |
this
|
|
dispose | |
---|---|
Removes the drop list functionality from the DOM element. |
drop | |
---|---|
Drops an item into this container. |
|
Parameters | |
item DragRef<any>
|
Item being dropped into the container. |
currentIndex number
|
Index at which the item should be inserted. |
previousIndex number
|
Index of the item when dragging started. |
previousContainer DropListRef<any>
|
Container from which the item got dragged in. |
isPointerOverContainer boolean
|
Whether the user's pointer was over the container when the item was dropped. |
distance Point
|
Distance the user has dragged since the start of the dragging sequence. |
event MouseEvent | TouchEvent = {} as any
|
Event that triggered the dropping sequence. |
dropPoint Point
|
|
enter | |
---|---|
Attempts to move an item into the container. |
|
Parameters | |
item DragRef<any>
|
Item that was moved into the container. |
pointerX number
|
Position of the item along the X axis. |
pointerY number
|
Position of the item along the Y axis. |
index? number
|
Index at which the item entered. If omitted, the container will try to figure it out automatically. |
exit | |
---|---|
Removes an item from the container after it was dragged into another container by the user. |
|
Parameters | |
item DragRef<any>
|
Item that was dragged out. |
getItemIndex | |
---|---|
Figures out the index of an item in the container. |
|
Parameters | |
item DragRef<any>
|
Item whose index should be determined. |
Returns | |
number
|
|
getScrollableParents | |
---|---|
Gets the scrollable parents that are registered with this drop container. |
|
Returns | |
readonly HTMLElement[]
|
|
isDragging | |
---|---|
Whether an item from this list is currently being dragged. |
isReceiving | |
---|---|
Whether the list is able to receive the item that is currently being dragged inside a connected drop list. |
|
Returns | |
boolean
|
|
start | |
---|---|
Starts dragging an item. |
withDirection | |
---|---|
Sets the layout direction of the drop list. |
|
Parameters | |
direction Direction
|
|
Returns | |
this
|
|
withElementContainer | |
---|---|
Configures the drop list so that a different element is used as the container for the dragged items. This is useful for the cases when one might not have control over the full DOM that sets up the dragging. Note that the alternate container needs to be a descendant of the drop list. |
|
Parameters | |
container HTMLElement
|
New element container to be assigned. |
Returns | |
this
|
|
withItems | |
---|---|
Sets the draggable items that are a part of this list. |
|
Parameters | |
items DragRef<any>[]
|
Items that are a part of this list. |
Returns | |
this
|
|
withOrientation | |
---|---|
Sets the orientation of the container. |
|
Parameters | |
orientation DropListOrientation
|
New orientation for the container. |
Returns | |
this
|
|
withScrollableParents | |
---|---|
Sets which parent elements are can be scrolled while the user is dragging. |
|
Parameters | |
elements HTMLElement[]
|
Elements that can be scrolled. |
Returns | |
this
|
|
Interfaces
DragRefConfig
Object that can be used to configure the behavior of DragRef.
Properties
Name | Description |
---|---|
|
Minimum amount of pixels that the user should drag, before the CDK initiates a drag sequence. |
|
Ref that the current drag item is nested in. |
|
Amount the pixels the user should drag before the CDK considers them to have changed the drag direction. |
|
|
Point
Point on the page or within an element.
Properties
Name | Description |
---|---|
|
|
|
CdkDragStart
Event emitted when the user starts dragging a draggable.
Properties
Name | Description |
---|---|
|
Native event that started the drag sequence. |
|
Draggable that emitted the event. |
CdkDragRelease
Event emitted when the user releases an item, before any animations have started.
Properties
Name | Description |
---|---|
|
Native event that caused the release event. |
|
Draggable that emitted the event. |
CdkDragEnd
Event emitted when the user stops dragging a draggable.
Properties
Name | Description |
---|---|
|
Distance in pixels that the user has dragged since the drag sequence started. |
|
Position where the pointer was when the item was dropped |
|
Native event that caused the dragging to stop. |
|
Draggable that emitted the event. |
CdkDragEnter
Event emitted when the user moves an item into a new drop container.
Properties
Name | Description |
---|---|
|
Container into which the user has moved the item. |
|
Index at which the item has entered the container. |
|
Item that was moved into the container. |
CdkDragExit
Event emitted when the user removes an item from a drop container by moving it into another one.
Properties
Name | Description |
---|---|
|
Container from which the user has a removed an item. |
|
Item that was removed from the container. |
CdkDragDrop
Event emitted when the user drops a draggable item inside a drop container.
Properties
Name | Description |
---|---|
|
Container in which the item was dropped. |
|
Current index of the item. |
|
Distance in pixels that the user has dragged since the drag sequence started. |
|
Position where the pointer was when the item was dropped |
|
Native event that caused the drop event. |
|
Whether the user's pointer was over the container when the item was dropped. |
|
Item that is being dropped. |
|
Container from which the item was picked up. Can be the same as the |
|
Index of the item when it was picked up. |
CdkDragMove
Event emitted as the user is dragging a draggable item.
Properties
Name | Description |
---|---|
|
Indicates the direction in which the user is dragging the element along each axis.
|
|
Distance in pixels that the user has dragged since the drag sequence started. |
|
Native event that is causing the dragging. |
|
Position of the user's pointer on the page. |
|
Item that is being dragged. |
CdkDragSortEvent
Event emitted when the user swaps the position of two drag items.
Properties
Name | Description |
---|---|
|
Container that the item belongs to. |
|
Index that the item is currently in. |
|
Item that is being sorted. |
|
Index from which the item was sorted previously. |
DragDropConfig
Object that can be used to configure the drag items and drop lists within a module or a component.
Properties
Name | Description |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Functions
moveItemInArray | |
---|---|
Moves an item one index in an array to another. |
|
Parameters | |
array T[]
|
Array in which to move the item. |
fromIndex number
|
Starting index of the item. |
toIndex number
|
Index to which the item should be moved. |
transferArrayItem | |
---|---|
Moves an item from one array to another. |
|
Parameters | |
currentArray T[]
|
Array from which to transfer the item. |
targetArray T[]
|
Array into which to put the item. |
currentIndex number
|
Index of the item in its current array. |
targetIndex number
|
Index at which to insert the item. |
copyArrayItem | |
---|---|
Copies an item from one array to another, leaving it in its original position in current array. |
|
Parameters | |
currentArray T[]
|
Array from which to copy the item. |
targetArray T[]
|
Array into which is copy the item. |
currentIndex number
|
Index of the item in its current array. |
targetIndex number
|
Index at which to insert the item. |
Type aliases
PreviewContainer
Possible places into which the preview of a drag item can be inserted.
global
- Preview will be inserted at the bottom of the<body>
. The advantage is that you don't have to worry aboutoverflow: hidden
orz-index
, but the item won't retain its inherited styles.parent
- Preview will be inserted into the parent of the drag item. The advantage is that inherited styles will be preserved, but it may be clipped byoverflow: hidden
or not be visible due toz-index
. Furthermore, the preview is going to have an effect over selectors like:nth-child
and some flexbox configurations.ElementRef<HTMLElement> | HTMLElement
- Preview will be inserted into a specific element. Same advantages and disadvantages asparent
.
type PreviewContainer = 'global' | 'parent' | ElementRef<HTMLElement> | HTMLElement;
DragStartDelay
Possible values that can be used to configure the drag start delay.
type DragStartDelay = number | {
touch: number;
mouse: number;
};
DragAxis
Possible axis along which dragging can be locked.
type DragAxis = 'x' | 'y';
DragConstrainPosition
Function that can be used to constrain the position of a dragged element.
type DragConstrainPosition = (point: Point, dragRef: DragRef) => Point;
DropListOrientation
Possible orientations for a drop list.
type DropListOrientation = 'horizontal' | 'vertical' | 'mixed';
Constants
CDK_DRAG_CONFIG
Injection token that can be used to configure the behavior of the drag&drop-related components.
const CDK_DRAG_CONFIG: InjectionToken<DragDropConfig>;
CDK_DROP_LIST_GROUP
Injection token that can be used to reference instances of CdkDropListGroup
. It serves as
alternative token to the actual CdkDropListGroup
class which could cause unnecessary
retention of the class and its directive metadata.
const CDK_DROP_LIST_GROUP: InjectionToken<CdkDropListGroup<unknown>>;
CDK_DROP_LIST
Injection token that can be used to reference instances of CdkDropList
. It serves as
alternative token to the actual CdkDropList
class which could cause unnecessary
retention of the class and its directive metadata.
const CDK_DROP_LIST: InjectionToken<CdkDropList<any>>;
CDK_DRAG_HANDLE
Injection token that can be used to reference instances of CdkDragHandle
. It serves as
alternative token to the actual CdkDragHandle
class which could cause unnecessary
retention of the class and its directive metadata.
const CDK_DRAG_HANDLE: InjectionToken<CdkDragHandle>;
CDK_DRAG_PREVIEW
Injection token that can be used to reference instances of CdkDragPreview
. It serves as
alternative token to the actual CdkDragPreview
class which could cause unnecessary
retention of the class and its directive metadata.
const CDK_DRAG_PREVIEW: InjectionToken<CdkDragPreview<any>>;
CDK_DRAG_PLACEHOLDER
Injection token that can be used to reference instances of CdkDragPlaceholder
. It serves as
alternative token to the actual CdkDragPlaceholder
class which could cause unnecessary
retention of the class and its directive metadata.
const CDK_DRAG_PLACEHOLDER: InjectionToken<CdkDragPlaceholder<any>>;