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"],
});

Permissions

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

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:

typestringRequired

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

urlstringRequired

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.

rotationnumberOptional

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:

typestringRequired

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

childrenarrayRequired

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.

rotationnumberOptional

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:

typestringRequired

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

refstringRequired

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.

rotationnumberOptional

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:

typestringRequired

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

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.

fontSizestringOptional

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.

textAlignstringOptional

The alignment of the text.

The available options include:

"start"
"center"
"end"

The default value is "start".

colorstringOptional

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

fontRefstringOptional

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

fontWeightstringOptional

The weight of the font.

The available options include:

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

The default value is "normal".

fontStylestringOptional

The style of the font.

The available options include:

"normal"
"italic"

The default value is "normal".

decorationstringOptional

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.

rotationnumberOptional

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:

typestringRequired

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

rangeobjectRequired

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.

rotationnumberOptional

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:

typestringRequired

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

pathsarrayRequired

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].dstringRequired

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].fillobjectRequired

The appearance of the path's interior.

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

paths[0].fill.dropTargetbooleanOptional

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

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

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

paths[0].fill.asset.typestringRequired

The type of asset to fill the shape.

Valid values include:

IMAGE
VIDEO

paths[0].fill.asset.refstringRequired

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

paths[0].strokeobjectRequired

The outline of the path.

paths[0].stroke.weightnumberRequired

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

paths[0].stroke.colorstringRequired

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

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

viewBoxobjectRequired

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

viewBox.widthnumberRequired

The width of the view box, in pixels.

viewBox.heightnumberRequired

The height of the view box, in pixels.

viewBox.topnumberRequired

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

viewBox.leftnumberRequired

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.

rotationnumberOptional

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:

typestringRequired

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

rowsarrayRequired

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]objectRequired

An individual row within a table.

rows[0].cellsarrayRequired

The cells that make up a row.

rows[0].cells[0]objectRequired

An individual cell within a row.

rows[0].cells[0].textobjectOptional

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

rows[0].cells[0].text.typestringRequired

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

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

rows[0].cells[0].fillobjectOptional

The background of the cell.

rows[0].cells[0].fill.colorstringOptional

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].colSpannumberOptional

The number of columns that the cell occupies.

rows[0].cells[0].rowSpannumberOptional

The number of rows that the cell occupies.

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

typestringRequired

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

refstringRequired

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.

rotationnumberOptional

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>