Skip navigation

Skip to main content

API reference
Intents: design
API reference

addNativeElement

API reference for the addNativeElement method.

This API is deprecated, and is no longer recommended for use, and should be removed from your app.

Adds a native element to the user's design.

Usage: Basic usage

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


const element: NativeElementWithBox = {
  type: 'text',
  children: ['Legacy element'],
  top: 100,
  left: 100,
  width: 200
};


await addNativeElement(element);
TYPESCRIPT

Parameters

elementobject
Required

The element to add to the user's design.

The type has been superseded by DesignElement.

An element that's natively supported by the Canva editor.

The type has been superseded by ImageElement.

An element that renders image content.

typestring
Required

The type of element.

The only valid value is "image".

altTextAltText | undefined
Required

A description of the image content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
dataUrlstring
Optional

A data URL that contains the image data.

refImageRef
Optional

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

The type has been superseded by VideoElement.

An element that renders video content.

typestring
Required

The type of element.

The only valid value is "video".

refVideoRef
Required

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

altTextAltText | undefined
Required

A description of the video content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.

The type has been superseded by EmbedElement.

An element that renders rich media, such as a YouTube video.

typestring
Required

The type of element.

The only valid value is "embed".

urlstring
Required

The URL of the rich media.

This URL must be supported by the Iframely API.

The type has been superseded by TextElement.

An element that renders text content.

typestring
Required

The type of element.

The only valid value is "text".

childrenstring[]
Required

The text content.

Only the first element in this array is used.

fontSizenumber
Optional

The size of the text.

Minimum: 1

Maximum: 100

Default value: 16

textAlignstring
Optional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
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.

Example

"#ff0099"
TS
fontRefFontRef
Optional

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

fontWeightFontWeight
Optional

The weight (thickness) of the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
Optional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstring
Optional

The decoration of the font.

Default value: "none"

Available values:

  • "none"
  • "underline"

The type has been superseded by ShapeElement.

An element that renders a vector shape.

typestring
Required

The type of element.

The only valid value is "shape".

viewBoxShapeViewBox
Required

Options for configuring the scale and cropping of the shape.

topnumber
Required

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

leftnumber
Required

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

widthnumber
Required

The width of the view box, in pixels.

heightnumber
Required

The height of the view box, in pixels.

pathsShapePath[]
Required

The paths that define the structure of the shape.

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

The shape of the path.

This is similar to the d attribute of an SVG's 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 by:
    • Using a Z command at the end of the path
    • Having the last coordinate match the first coordinate
fillFill
Required

The appearance of the path's interior.

dropTargetboolean
Optional

If true, users can replace a fill by dropping an image or video onto it.

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.

Example

"#ff0099"
TS
assetobject
Optional

An image or video to use as the fill.

An image asset that fills a path's interior.

typestring
Required

The type of fill.

The only valid value is "image".

refImageRef
Required

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

altTextAltText
Optional

A description of the image content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.

A video asset that fills a path's interior.

typestring
Required

The type of fill.

The only valid value is "video".

refVideoRef
Required

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

altTextAltText
Optional

A description of the image content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
strokePathStroke
Optional

The outline of the path.

weightnumber
Required

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

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.

Example

"#ff0099"
TS
strokeAlignstring
Required

The alignment of the stroke.

The only valid value is "inset".

The type has been superseded by GroupElement.

An element that contains two or more elements.

typestring
Required

The type of element.

The only valid value is "group".

childrenGroupContentAtPoint[]
Required

The elements to render within the group.

  • Each element within a group must have dimensions and a position.
  • The dimensions and positions are relative to the dimensions and positions of the group.

The type has been superseded by ElementAtPoint.

An element that's natively supported by the Canva editor and has positional properties.

The type has been superseded by ImageElementAtPoint.

An element that renders image content and has positional properties.

typestring
Required

The type of element.

The only valid value is "image".

altTextAltText | undefined
Required

A description of the image content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
topnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumber
Required

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumber
Required

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

dataUrlstring
Optional

A data URL that contains the image data.

refImageRef
Optional

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

The type has been superseded by VideoElementAtPoint.

An element that renders video content and has positional properties.

typestring
Required

The type of element.

The only valid value is "video".

refVideoRef
Required

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

altTextAltText | undefined
Required

A description of the video content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
topnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumber
Required

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumber
Required

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

The type has been superseded by EmbedElementAtPoint.

An element that renders rich media, such as a YouTube video, and has positional properties.

typestring
Required

The type of element.

The only valid value is "embed".

urlstring
Required

The URL of the rich media.

This URL must be supported by the Iframely API.

topnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumber
Required

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumber
Required

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

The type has been superseded by TextElementAtPoint.

An element that renders text content and has positional properties.

typestring
Required

The type of element.

The only valid value is "text".

childrenstring[]
Required

The text content.

Only the first element in this array is used.

topnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

fontSizenumber
Optional

The size of the text.

Minimum: 1

Maximum: 100

Default value: 16

textAlignstring
Optional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
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.

Example

"#ff0099"
TS
fontRefFontRef
Optional

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

fontWeightFontWeight
Optional

The weight (thickness) of the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
Optional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstring
Optional

The decoration of the font.

Default value: "none"

Available values:

  • "none"
  • "underline"
rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

widthnumber
Optional

The width of the element, in pixels.

Minimum: 0

Maximum: 32767

The type has been superseded by ShapeElementAtPoint.

An element that renders a vector shape and has positional properties.

typestring
Required

The type of element.

The only valid value is "shape".

viewBoxShapeViewBox
Required

Options for configuring the scale and cropping of the shape.

topnumber
Required

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

leftnumber
Required

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

widthnumber
Required

The width of the view box, in pixels.

heightnumber
Required

The height of the view box, in pixels.

pathsShapePath[]
Required

The paths that define the structure of the shape.

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

The shape of the path.

This is similar to the d attribute of an SVG's 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 by:
    • Using a Z command at the end of the path
    • Having the last coordinate match the first coordinate
fillFill
Required

The appearance of the path's interior.

dropTargetboolean
Optional

If true, users can replace a fill by dropping an image or video onto it.

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.

Example

"#ff0099"
TS
assetobject
Optional

An image or video to use as the fill.

An image asset that fills a path's interior.

typestring
Required

The type of fill.

The only valid value is "image".

refImageRef
Required

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

altTextAltText
Optional

A description of the image content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.

A video asset that fills a path's interior.

typestring
Required

The type of fill.

The only valid value is "video".

refVideoRef
Required

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

altTextAltText
Optional

A description of the image content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
strokePathStroke
Optional

The outline of the path.

weightnumber
Required

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

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.

Example

"#ff0099"
TS
strokeAlignstring
Required

The alignment of the stroke.

The only valid value is "inset".

topnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumber
Required

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumber
Required

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

The type has been superseded by GroupElementAtPoint.

An element that contains two or more elements and has positional properties.

typestring
Required

The type of element.

The only valid value is "group".

childrenGroupContentAtPoint[]
Required

The elements to render within the group.

  • Each element within a group must have dimensions and a position.
  • The dimensions and positions are relative to the dimensions and positions of the group.
topnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumber
Required

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumber
Required

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

Returns

Promise<void>