addNativeElement

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

Adds a native element to a user's design.

To learn more, see:

Usage

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

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

Scopes

Before an app that uses this method can be submitted for review, the canva:design:content:write scope must be enabled through the Developer Portal. To learn more, see Configuring scopes.

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.

This URL must be supported by Iframely. To learn more, see What URLs to send to Iframely⁠(opens in a new tab or window).

widthnumber

Sometimes required

The width of the element, in pixels.

If height is a number, this can be set to "auto".

heightnumber

Sometimes required

The height of the element, in pixels.

If width is a number, this can be set to "auto".

topnumber

Sometimes required

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

The container could be a page, a group, or an app element.

leftnumber

Sometimes required

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

The container could be a page, a group, or an app element.

rotationnumber

Optional

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

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the width, height, top, and left properties.

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.

Each element must have the following properties:

width
height
top
left

Group elements can't contain group elements.

widthnumber

Sometimes required

The width of the element, in pixels.

If height is a number, this can be set to "auto".

heightnumber

Sometimes required

The height of the element, in pixels.

If width is a number, this can be set to "auto".

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.

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the width, height, top, and left properties.

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.

If height is a number, this can be set to "auto".

heightnumber

Sometimes required

The height of the element, in pixels.

If width is a number, this can be set to "auto".

topnumber

Sometimes required

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

The container could be a page, a group, or an app element.

leftnumber

Sometimes required

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

The container could be a page, a group, or an app element.

rotationnumber

Optional

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

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the width, height, top, and left properties.

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

typestring

Required

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

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.

fontSizestring

Optional

The size of the text, in pixels. This must be an integer between 1 and 1000 (inclusive). The default value is 16.

In the user interface, the font size is displayed as points (pts), not pixels. This means the font size defined here will be different from what's shown to the user.

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the top, left, and width properties.

textAlignstring

Optional

The alignment of the text.

The available options include:

"start"
"center"
"end"

The default value is "start".

colorstring

Optional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol — for example, "#ff0099".

The default value is "#000000".

fontRefstring

Optional

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

fontWeightstring

Optional

The weight of the font.

The available options include:

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

The default value is "normal".

fontStylestring

Optional

The style of the font.

The available options include:

"normal"
"italic"

The default value is "normal".

decorationstring

Optional

The decoration of the font.

The available options include:

"none"
"underline"

The default value is "none".

widthnumber

Sometimes required

The width of the element, in pixels.

topnumber

Sometimes required

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

The container could be a page, a group, or an app element.

leftnumber

Sometimes required

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

The container could be a page, a group, or an app element.

rotationnumber

Optional

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

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the top, left, and width properties.

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

typestring

Required

The type of element. For richtext elements, this must be "RICHTEXT".

rangeobject

Required

A range of formatted text created with the createRichtextRange method.

widthnumber

Sometimes required

The width of the element, in pixels.

topnumber

Sometimes required

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

The container could be a page, a group, or an app element.

leftnumber

Sometimes required

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

The container could be a page, a group, or an app element.

rotationnumber

Optional

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

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the top, left, and width properties.

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.

There must be between 1 and 30 paths. The maximum combined size of all paths must not exceed 2kb. The maximum number of unique fill colors across all paths is 6.

paths[0].dstring

Required

The shape of the path.

This accepts the same value as the d attribute of the SVG <path> element, with some limitations:

The path must start with an M command
The path must not have more than one M command
The path must not use the Q command
The path must be closed, either with a Z command at the end or by having the last coordinate match the first coordinate

paths[0].fillobject

Required

The appearance of the path's interior.

Only one type of fill — color, image, or video — can be set.

paths[0].fill.dropTargetboolean

Optional

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

Although the dropTarget property is optional, we encourage you to set it to prevent breaking in potential future API changes. For image fills dropTarget can be false, but for video fills it must be true.

paths[0].fill.colorstring

Optional

The color of the fill as a hex code.

The hex code must include all six characters and be prefixed with a # symbol — for example, "#ff0099".

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.

Valid values include:

IMAGE
VIDEO

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.

The hex code must include all six characters and be prefixed with a # symbol — for example, "#ff0099".

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.

If height is a number, this can be set to "auto".

heightnumber

Sometimes required

The height of the element, in pixels.

If width is a number, this can be set to "auto".

topnumber

Sometimes required

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

The container could be a page, a group, or an app element.

leftnumber

Sometimes required

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

The container could be a page, a group, or an app element.

rotationnumber

Optional

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

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the width, height, top, and left properties.

This API is in preview mode and may experience breaking changes. Apps that use this API will not pass the review process and can't be made available on the Apps Marketplace.

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

typestring

Required

The type of element. For table elements, this must be "TABLE".

rowsarray

Required

The rows that make up a table. A table must have at least one row, one column, and no more than 225 cells.

rows[0]object

Required

An individual row within a table.

rows[0].cellsarray

Required

The cells that make up a row.

rows[0].cells[0]object

Required

An individual cell within a row.

rows[0].cells[0].textobject

Optional

A text element to set as the contents of the cell.

rows[0].cells[0].text.typestring

Required

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

rows[0].cells[0].text.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.

rows[0].cells[0].fillobject

Optional

The background of the cell.

rows[0].cells[0].fill.colorstring

Optional

The background color of the cell as a hex code. The hex code must include all six characters and be prefixed with a # symbol — for example, "#ff0099".

rows[0].cells[0].colSpannumber

Optional

The number of columns that the cell occupies.

rows[0].cells[0].rowSpannumber

Optional

The number of rows that the cell occupies.

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.

If height is a number, this can be set to "auto".

heightnumber

Sometimes required

The height of the element, in pixels.

If width is a number, this can be set to "auto".

topnumber

Sometimes required

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

The container could be a page or a group.

leftnumber

Sometimes required

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

The container could be a page or a group.

rotationnumber

Optional

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

This property doesn't have an effect unless you also set position properties for the element. To set a position, you must provide the width, height, top, and left properties.

Returns

Promise<void>