Skip navigation

Skip to main content

API reference
API reference

ui.startDrag

API reference for the ui.startDrag 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.

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.

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.

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>