API reference

Asset

Data

Design

addAudioTrack addNativeElement addPage getCurrentPageContext getDefaultPageDimensions initAppElement requestExport selection.registerOnChange selection.setContent setCurrentPageBackground ui.makeDraggable ui.startDrag

User

auth.getCanvaUserToken auth.requestAuthentication

API reference

addNativeElement

API reference for the addNativeElement method.

Adds a native element to a user's design.

To learn more, see:

Usage

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

(async () => {
  await addNativeElement({
    type: "TEXT",
    children: ["Hello world"],
  });
})();

Rate limit

This method has a rate limit of 20 requests every 10 seconds.

Parameters

The expected parameters depend on the type of element being added to the design:

To add an embed element to the user's design, set the following parameters:

#typestring

Required

The type of element. For embed elements, this must be "EMBED".

#urlstring

Required

The URL of the embeddable media.

#widthnumber

Sometimes required

The width of the element, in pixels.

#heightnumber

Sometimes required

The height of the element, in pixels.

#topnumber

Sometimes required

The distance from the top edge of the container, in pixels.

#leftnumber

Sometimes required

The distance from the left edge of the container, in pixels.

#rotationnumber

Optional

The rotation of the element, in degrees. This must be a number between -180 and 180.

To add a group element to the user's design, set the following parameters:

#typestring

Required

The type of element. For group elements, this must be "GROUP".

#childrenarray

Required

The elements to include in the group.

#widthnumber

Sometimes required

The width of the element, in pixels.

#heightnumber

Sometimes required

The height of the element, in pixels.

#topnumber

Sometimes required

The distance from the top edge of the page, in pixels.

#leftnumber

Sometimes required

The distance from the left edge of the page, in pixels.

#rotationnumber

Optional

The rotation of the element, in degrees. This must be a number between -180 and 180.

To add an image element to the user's design, set the following parameters:

#typestring

Required

The type of element. For image elements, this must be "IMAGE".

#refstring

Required

A unique identifier that points to an image in Canva's backend.

#widthnumber

Sometimes required

The width of the element, in pixels.

#heightnumber

Sometimes required

The height of the element, in pixels.

#topnumber

Sometimes required

The distance from the top edge of the container, in pixels.

#leftnumber

Sometimes required

The distance from the left edge of the container, in pixels.

#rotationnumber

Optional

The rotation of the element, in degrees. This must be a number between -180 and 180.

To add a shape element to the user's design, set the following parameters:

#typestring

Required

The type of element. For shape elements, this must be "SHAPE".

#pathsarray

Required

The paths that define the shape of the element.

#paths[0].dstring

Required

The shape of the path.

#paths[0].fillobject

Required

The appearance of the path's interior.

#paths[0].fill.dropTargetboolean

Optional

If true, users can drop images or videos onto the path to use them as a fill.

#paths[0].fill.colorstring

Optional

The color of the fill as a hex code.

#paths[0].fill.assetobject

Optional

If set, a user can fill a shape with an asset.

#paths[0].fill.asset.typestring

Required

The type of asset to fill the shape.

#paths[0].fill.asset.refstring

Required

The unique identifier of the paths[0].fill.asset.type asset to fill the shape.

#paths[0].strokeobject

Required

The outline of the path.

#paths[0].stroke.weightnumber

Required

The weight of the stroke. This must be an integer between 0 and 100.

#paths[0].stroke.colorstring

Required

The color of the stroke as a hex code.

#paths[0].stroke.strokeAlignstring

Required

The alignment of the stroke. The only supported value is "inset".

#viewBoxobject

Required

The scale and cropping of a shape. This is similar to the viewBox attribute of a HTMLSVGElement.

#viewBox.widthnumber

Required

The width of the view box, in pixels.

#viewBox.heightnumber

Required

The height of the view box, in pixels.

#viewBox.topnumber

Required

The distance of the shape from the top edge of the element, in pixels.

#viewBox.leftnumber

Required

The distance of the shape from the left edge of the element, in pixels.

#widthnumber

Sometimes required

The width of the element, in pixels.

#heightnumber

Sometimes required

The height of the element, in pixels.

#topnumber

Sometimes required

The distance from the top edge of the container, in pixels.

#leftnumber

Sometimes required

The distance from the left edge of the container, in pixels.

#rotationnumber

Optional

The rotation of the element, in degrees. This must be a number between -180 and 180.

To add a text element to the user's design, set the following parameters:

#typestring

Required

The type of element. For text elements, this must be "TEXT".

#childrenarray

Required

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

#fontSizestring

Optional

The size of the text. This must be an integer between 1 and 1000. The default value is 16.

#textAlignstring

Optional

The alignment of the text.

#colorstring

Optional

The color of the text as a hex code.

#fontWeightstring

Optional

The weight of the font.

#fontStylestring

Optional

The style of the font.

#decorationstring

Optional

The decoration of the font.

#widthnumber

Sometimes required

The width of the element, in pixels.

#topnumber

Sometimes required

The distance from the top edge of the container, in pixels.

#leftnumber

Sometimes required

The distance from the left edge of the container, in pixels.

#rotationnumber

Optional

The rotation of the element, in degrees. This must be a number between -180 and 180.

To add a video element to the user's design, set the following parameters:

#typestring

Required

The type of element. For video elements, this must be "VIDEO".

#refstring

Required

A unique identifier that points to a video in Canva's backend.

#widthnumber

Sometimes required

The width of the element, in pixels.

#heightnumber

Sometimes required

The height of the element, in pixels.

#topnumber

Sometimes required

The distance from the top edge of the page, in pixels.

#leftnumber

Sometimes required

The distance from the left edge of the container, in pixels.

#rotationnumber

Optional

The rotation of the element, in degrees. This must be a number between -180 and 180.

Returns

Promise<void>