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:

eventobjectRequired

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

dragDataobjectRequired

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

dragData.typestringRequired

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

dragData.embedUrlstringRequired

The URL of the embeddable media.

dragData.previewUrlstringRequired

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.previewSizeobjectRequired

The dimensions of the drag preview, in pixels.

dragData.previewSize.widthnumberRequired

The width of the drag preview, in pixels.

dragData.previewSize.heightnumberRequired

The height of the drag preview, in pixels.

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

eventobjectRequired

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

dragDataobjectRequired

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

dragData.typestringRequired

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

dragData.titlestringRequired

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

dragData.durationMsnumberRequired

The duration of the audio file, in milliseconds.

dragData.resolveAudioReffunctionRequired

A function that returns the result of the upload method.

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

eventobjectRequired

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

dragDataobjectRequired

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

dragData.typestringRequired

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

dragData.resolveImageReffunctionRequired

A function that returns the result of the upload method.

dragData.previewSizeobjectRequired

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

dragData.previewSize.widthnumberRequired

The width of the drag preview, in pixels.

dragData.previewSize.heightnumberRequired

The height of the drag preview, in pixels.

dragData.fullSizeobjectOptional

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

dragData.fullSize.widthnumberRequired

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

dragData.fullSize.heightnumberRequired

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

dragData.previewUrlstringOptional

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:

eventobjectRequired

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

dragDataobjectRequired

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

dragData.typestringRequired

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

dragData.childrenarrayRequired

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.textAlignstringOptional

The horizontal alignment of the text.

The available options include:

"start"
"center"
"end"

The default value is "start".

dragData.fontWeightstringOptional

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.fontStylestringOptional

The style of the font.

The available options include:

"normal"
"italic"

The default value is "normal".

dragData.decorationstringOptional

The decoration to apply to the font.

The available options include:

"normal"
"underline"

The default value is "normal".

dragData.fontRefstringOptional

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:

eventobjectRequired

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

dragDataobjectRequired

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

dragData.typestringRequired

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

dragData.resolveVideoReffunctionRequired

A function that returns the result of the upload method.

dragData.previewSizeobjectRequired

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

dragData.previewSize.widthnumberRequired

The width of the drag preview, in pixels.

dragData.previewSize.heightnumberRequired

The height of the drag preview, in pixels.

dragData.previewUrlstringRequired

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.fullSizeobjectOptional

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>