Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Migration FAQ and Migration guide.
API reference
API reference

ui.makeDraggable

API reference for the ui.makeDraggable method.
This version of the API is deprecated. This version will soon be unsupported. You should use a stable version of the API in your app.

Makes a DOM node draggable. When the user drags and drops the node into their design, a specified type of element — for example, an image — will be added at the drop coordinates.

To learn more, see Drag and drop.

Usage

import { ui } from "@canva/design";


const node = document.querySelector("#some-node");


if (!(node instanceof HTMLElement)) {
  throw new Error(`DOM node does not exist`);
}


ui.makeDraggable({
  node,
  dragData: {
    type: "TEXT",
    children: ["Hello world"],
  },
  onDragStart: () => {
    console.log("The drag event has started");
  },
  onDragEnd: () => {
    console.log("The drag event has ended");
  },
});
TS

Parameters

The expected parameters depend on what will be added to the user's design at the end of a drag event:

When adding an audio track to a design, set the following properties:

optionsobject
REQUIRED

The options for configuring the drag and drop behavior of a DOM node.

options.nodeHTMLElement
REQUIRED

The DOM node to make draggable.

options.onDragStartfunction
REQUIRED

A callback function that runs at the start of a drag event.

options.onDragEndfunction
REQUIRED

A callback function that runs at the end of a drag event. This function always runs, regardless of whether or not the user successfully drops something into their design.

options.dragDataobject
REQUIRED

The options for configuring what's added to the user's design at the end of a drag event.

options.dragData.typestring
REQUIRED

The type of element to add to the design. For audio tracks, this must be "AUDIO".

options.dragData.titlestring
REQUIRED

A human-readable title that appears in the Canva editor.

options.dragData.durationMsnumber
REQUIRED

The duration of the audio file, in milliseconds.

options.dragData.resolveAudioReffunction
REQUIRED

A function that returns the result of the upload method.

When adding an image to a design, set the following properties:

optionsobject
REQUIRED

The options for configuring the drag and drop behavior of a DOM node.

options.nodeHTMLElement
REQUIRED

The DOM node to make draggable.

options.onDragStartfunction
REQUIRED

A callback function that runs at the start of a drag event.

options.onDragEndfunction
REQUIRED

A callback function that runs at the end of a drag event. This function always runs, regardless of whether or not the user successfully drops something into their design.

options.dragDataobject
OPTIONAL

The options for configuring what's added to the user's design at the end of a drag event.

options.dragData.typestring
REQUIRED

The type of element to add to the design. For images, this must be "IMAGE".

options.dragData.resolveImageReffunction
REQUIRED

A function that returns the result of the upload method.

options.dragData.previewSizeobject
REQUIRED

The dimensions of the drag preview, in pixels. The dimensions should have the same aspect ratio as the full-size image.

options.dragData.previewSize.widthnumber
REQUIRED

The width of the drag preview, in pixels.

options.dragData.previewSize.heightnumber
REQUIRED

The height of the drag preview, in pixels.

options.dragData.fullSizeobject
OPTIONAL

The dimensions of the full-size image. If omitted, the drag preview dimensions are used.

options.dragData.fullSize.widthnumber
REQUIRED

The width of the full-size image, in pixels.

options.dragData.fullSize.heightnumber
REQUIRED

The height of the full-size image, in pixels.

options.dragData.previewSrcstring
OPTIONAL

The URL or data URL of the image to use for the drag preview. This image will appear under the user's cursor during the drag event. If omitted, the full-size image will be used.

When adding text to a design, set the following properties:

optionsobject
REQUIRED

The options for configuring the drag and drop behavior of a DOM node.

options.nodeHTMLElement
REQUIRED

The DOM node to make draggable.

options.onDragStartfunction
REQUIRED

A callback function that runs at the start of a drag event.

options.onDragEndfunction
REQUIRED

A callback function that runs at the end of a drag event. This function always runs, regardless of whether or not the user successfully drops something into their design.

options.dragDataobject
REQUIRED

The options for configuring what's added to the user's design at the end of a drag event.

options.dragData.typestring
REQUIRED

The type of element to add to the design. For text, this must be "TEXT".

options.dragData.childrenarray
REQUIRED

The text to add to the user's design, provided as an array of strings.

For the time being, the array is only allowed to have one item. In the future, each element in the array will be rendered as a separate line of text.

options.dragData.textAlignstring
OPTIONAL

The horizontal alignment of the text.

The available options include:

  • "start"
  • "center"
  • "end"

The default value is "start".

options.dragData.fontWeightstring
OPTIONAL

The weight (boldness) of the font.

The available options include:

  • "normal"
  • "bold"

The default value is "normal".

options.dragData.fontStylestring
OPTIONAL

The style of the font.

The available options include:

  • "normal"
  • "italic"

The default value is "normal".

options.dragData.decorationstring
OPTIONAL

The decoration to apply to the font.

The available options include:

  • "normal"
  • "underline"

The default value is "normal".

When adding a video to a design, set the following properties:

optionsobject
REQUIRED

The options for configuring the drag and drop behavior of a DOM node.

options.nodeHTMLElement
REQUIRED

The DOM node to make draggable.

options.onDragStartfunction
REQUIRED

A callback function that runs at the start of a drag event.

options.onDragEndfunction
REQUIRED

A callback function that runs at the end of a drag event. This function always runs, regardless of whether or not the user successfully drops something into their design.

options.dragDataobject
REQUIRED

The options for configuring what's added to the user's design at the end of a drag event.

options.dragData.typestring
REQUIRED

The type of element to add to the design. For videos, this must be "VIDEO".

options.dragData.resolveVideoReffunction
REQUIRED

A function that returns the result of the upload method.

options.dragData.previewSizeobject
REQUIRED

The dimensions of the drag preview, in pixels. The dimensions should have the same aspect ratio as the full-size video.

options.dragData.previewSize.widthnumber
REQUIRED

The width of the drag preview, in pixels.

options.dragData.previewSize.heightnumber
REQUIRED

The height of the drag preview, in pixels.

options.dragData.previewSrcstring
REQUIRED

The URL or data URL of the image to use for the drag preview. This image will appear under the user's cursor during the drag event. If omitted, the full-size image will be used.

options.dragData.fullSizeobject
OPTIONAL

The dimensions of the full-size video, in pixels. If omitted, the drag preview dimensions are used.

options.dragData.fullSize.widthnumber
SOMETIMES REQUIRED

The width of the full-size video, in pixels.

options.dragData.fullSize.heightnumber
SOMETIMES REQUIRED

The height of the full-size video, in pixels.

Returns

Promise<void>