ui.startDrag

API reference for the ui.startDrag method.

Handles a drag event. At the end of the drag event, the specified type of element — for example, an image — will be added at the drop coordinates.

Usage

import React from "react";
import { Text, TypographyCard } from "@canva/app-ui-kit";
import { addNativeElement, ui } from "@canva/design";

export function App() {
  return (
    <TypographyCard
      ariaLabel="Add text to design"
      onClick={() => {
        addNativeElement({
          type: "TEXT",
          children: ["Add text into a design"],
        });
      }}
      onDragStart={(event: React.DragEvent<HTMLElement>) => {
        ui.startDrag(event, {
          type: "TEXT",
          children: ["Add text into a design"],
        });
      }}
    >
      <Text>Add text into a design</Text>
    </TypographyCard>
  );
}

tsx

Parameters

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

#eventobject

Required

The event that's fired when the user starts dragging an element.

#dragDataobject

Required

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

#dragData.typestring

Required

The type of element to add to the design. For embeds, this must be "EMBED".

#dragData.embedUrlstring

Required

The URL of the embeddable media.

#dragData.previewUrlstring

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.

#dragData.previewSizeobject

Required

The dimensions of the drag preview, in pixels.

#dragData.previewSize.widthnumber

Required

The width of the drag preview, in pixels.

#dragData.previewSize.heightnumber

Required

The height of the drag preview, in pixels.

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

#eventobject

Required

The event that's fired when the user starts dragging an element.

#dragDataobject

Required

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

#dragData.typestring

Required

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

#dragData.titlestring

Required

A human readable title that appears in the Canva editor.

#dragData.durationMsnumber

Required

The duration of the audio file, in milliseconds.

#dragData.resolveAudioReffunction

Required

A function that returns the result of the upload method.

For image elements, the expected parameters depend on the format of the image data:

#eventobject

Required

The event that's fired when the user starts dragging an element.

#dragDataobject

Required

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

#dragData.typestring

Required

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

#dragData.resolveImageReffunction

Required

A function that returns the result of the upload method.

#dragData.previewSizeobject

Required

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

#dragData.previewSize.widthnumber

Required

The width of the drag preview, in pixels.

#dragData.previewSize.heightnumber

Required

The height of the drag preview, in pixels.

#dragData.fullSizeobject

Optional

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

#dragData.fullSize.widthnumber

Required

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

#dragData.fullSize.heightnumber

Required

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

#dragData.previewUrlstring

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 parameters:

#eventobject

Required

The event that's fired when the user starts dragging an element.

#dragDataobject

Required

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

#dragData.typestring

Required

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

#dragData.childrenarray

Required

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

#dragData.textAlignstring

Optional

The horizontal alignment of the text.

The available options include:

"start"
"center"
"end"

The default value is "start".

#dragData.fontWeightstring

Optional

The weight (boldness) of the font.

The available options include:

"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"

The default value is "normal".

#dragData.fontStylestring

Optional

The style of the font.

The available options include:

"normal"
"italic"

The default value is "normal".

#dragData.decorationstring

Optional

The decoration to apply to the font.

The available options include:

"normal"
"underline"

The default value is "normal".

#dragData.fontRefstring

Optional

A unique identifier that references a font asset in Canva's backend. To learn more, see Creating text.

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

#eventobject

Required

The event that's fired when the user starts dragging an element.

#dragDataobject

Required

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

#dragData.typestring

Required

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

#dragData.resolveVideoReffunction

Required

A function that returns the result of the upload method.

#dragData.previewSizeobject

Required

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

#dragData.previewSize.widthnumber

Required

The width of the drag preview, in pixels.

#dragData.previewSize.heightnumber

Required

The height of the drag preview, in pixels.

#dragData.previewUrlstring

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.

#dragData.fullSizeobject

Optional

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

#dragData.fullSize.widthnumber

Sometimes required

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

#dragData.fullSize.heightnumber

Sometimes required

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

Returns

Promise<void>