Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Migration FAQ and Migration guide.
API reference
Intents: design
API reference

ElementStateBuilder

API reference for the ElementStateBuilder type.
This version of the API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Provides methods for creating element states.

These methods don't add the elements to the design. They only return elements that can be added to a design, such as with the insertAfter method.

Methods

createRectElementfunction
Required

Creates a rect element state.

Parameters

optsCreateRectElementOpts
Required

Options for creating the rect element.

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.

heightnumber
Required

A height, in pixels.

rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Optional

Transparency as a percentage.

Minimum: 0

Maximum: 1

fillFillOpts
Optional

Describes how a fill is filled with color or media.

If both media and color are defined, media takes precedence.

colorContainerColorContainerOpts
Sometimes required
typestringRead-only
Required

The type of color.

This must be "solid".

colorstring
Required

The color of the fill. This must be a valid, six-digit hex code, prefixed with a # symbol.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Example

"#ff0099"
TS
mediaContainerMediaContainerOpts
Sometimes required

Options for creating a media fill in the element state builder

Options for creating an image fill in the element state builder

typestring
Required

The type of media.

This must be "image".

imageRefImageRef
Required

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

flipXboolean
Optional

If true, the image is flipped horizontally.

flipYboolean
Optional

If true, the image is flipped vertically.

Options for creating a video fill in the element state builder

typestring
Required

The type of media.

This must be "video".

videoRefVideoRef
Required

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

flipXboolean
Optional

If true, the video is flipped horizontally.

flipYboolean
Optional

If true, the video is flipped vertically.

strokeStrokeOpts
Optional

The outline of the rect.

weightnumber
Required

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorContainerColorContainerOpts
Required

The color of the stroke.

typestringRead-only
Required

The type of color.

This must be "solid".

colorstring
Required

The color of the fill. This must be a valid, six-digit hex code, prefixed with a # symbol.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Example

"#ff0099"
TS

Returns

A state that creates a rectangle element.

The rectangle can be filled with image content, video content, or a solid color.

typestringRead-only

The type of content.

This must be "rect".

fillFillStateRead-only

The appearance of the rectangle's interior.

mediaContainerundefined | MediaFillState

The media fill for the path, if any.

A state that creates an image fill.

typestringRead-only

The type of media.

This must be "image".

imageRefImageRefRead-only

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

flipXboolean

If true, the image is flipped horizontally.

flipYboolean

If true, the image is flipped vertically.

A state that creates a video fill.

typestringRead-only

The type of media.

This must be "video".

videoRefVideoRefRead-only

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

flipXboolean

If true, the video is flipped horizontally.

flipYboolean

If true, the video is flipped vertically.

colorContainerundefined | ColorFillState

The color fill for the path, if any.

A state that creates a solid color fill.

typestringRead-only

The type of color.

This must be "solid".

colorstring

The color of the fill. This must be a valid, six-digit hex code, prefixed with a # symbol.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Example

"#ff0099"
TS

Represents something that's not supported by the Apps SDK.

typestringRead-only

This must be "unsupported".

strokeStrokeStateRead-only

The outline of the rectangle.

weightnumber

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorContainerColorFillState

The color of the stroke.

A state that creates a solid color fill.

typestringRead-only

The type of color.

This must be "solid".

colorstring

The color of the fill. This must be a valid, six-digit hex code, prefixed with a # symbol.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Example

"#ff0099"
TS

Represents something that's not supported by the Apps SDK.

typestringRead-only

This must be "unsupported".

widthnumberRead-only

A width, in pixels.

heightnumberRead-only

A height, in pixels.

lockedbooleanRead-only

If true, the element is locked and cannot be modified.

topnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-only

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-only

Transparency as a percentage.

Minimum: 0

Maximum: 1

createShapeElementfunction
Required

Creates a shape element state.

Parameters

optsCreateShapeElementOpts
Required

Options for creating the shape element.

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.

heightnumber
Required

A height, in pixels.

viewBoxAlignedBoxStateRead-only
Required

The scale and cropping of the shape.

topnumberRead-only
Required

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

leftnumberRead-only
Required

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

widthnumberRead-only
Required

The width of the view box, in pixels.

heightnumberRead-only
Required

The height of the view box, in pixels.

pathsPathOpts[]
Required

The paths that define the structure of the shape.

  • Must have between 1 and 30 paths.
  • Total size of all paths must not exceed 2kb.
  • Maximum of 6 unique fill colors across all paths.
dstring
Required
fillPathFillOpts
Optional

Describes how a fill is filled with color or media.

If both media and color are defined, media takes precedence.

colorContainerColorContainerOpts
Sometimes required
typestringRead-only
Required

The type of color.

This must be "solid".

colorstring
Required

The color of the fill. This must be a valid, six-digit hex code, prefixed with a # symbol.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Example

"#ff0099"
TS
mediaContainerMediaContainerOpts
Sometimes required

Options for creating a media fill in the element state builder

Options for creating an image fill in the element state builder

typestring
Required

The type of media.

This must be "image".

imageRefImageRef
Required

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

flipXboolean
Optional

If true, the image is flipped horizontally.

flipYboolean
Optional

If true, the image is flipped vertically.

Options for creating a video fill in the element state builder

typestring
Required

The type of media.

This must be "video".

videoRefVideoRef
Required

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

flipXboolean
Optional

If true, the video is flipped horizontally.

flipYboolean
Optional

If true, the video is flipped vertically.

isMediaEditableboolean
Sometimes required
strokeStrokeOpts
Optional

The outline of the path.

weightnumber
Required

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorContainerColorContainerOpts
Required

The color of the stroke.

typestringRead-only
Required

The type of color.

This must be "solid".

colorstring
Required

The color of the fill. This must be a valid, six-digit hex code, prefixed with a # symbol.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Example

"#ff0099"
TS
rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Optional

Transparency as a percentage.

Minimum: 0

Maximum: 1

Returns

A state that creates a vector shape element.

typestringRead-only

The type of content.

This must be "shape".

viewBoxAlignedBoxStateRead-only

The scale and cropping of the shape.

topnumberRead-only

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

leftnumberRead-only

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

widthnumberRead-only

The width of the view box, in pixels.

heightnumberRead-only

The height of the view box, in pixels.

pathsListState<PathState>Read-only

The paths that define the structure of the shape.

  • Must have between 1 and 30 paths.
  • Total size of all paths must not exceed 2kb.
  • Maximum of 6 unique fill colors across all paths.

For more information, see ListState.

widthnumberRead-only

A width, in pixels.

heightnumberRead-only

A height, in pixels.

lockedbooleanRead-only

If true, the element is locked and cannot be modified.

topnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-only

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-only

Transparency as a percentage.

Minimum: 0

Maximum: 1

createEmbedElementfunction
Required

Creates an embed element state.

Parameters

optsCreateEmbedElementOpts
Required

Options for creating the embed element.

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.

heightnumber
Required

A height, in pixels.

urlstring
Required

The URL of the rich media.

This URL must be supported by the Iframely API.

rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Optional

Transparency as a percentage.

Minimum: 0

Maximum: 1

Returns

A state that creates an embed element, such as a YouTube video.

typestringRead-only

The type of content.

This must be "embed".

urlstringRead-only

The URL of the rich media.

This URL must be supported by the Iframely API.

widthnumberRead-only

A width, in pixels.

heightnumberRead-only

A height, in pixels.

lockedbooleanRead-only

If true, the element is locked and cannot be modified.

topnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-only

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-only

Transparency as a percentage.

Minimum: 0

Maximum: 1

createTextElementfunction
Required

Creates a text element state.

Parameters

optsCreateTextElementOpts
Required

Options for creating the text element.

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.

textobject
Required

The text content.

regionsTextRegion[]
Required

A region of richtext.

textstring
Required

The plaintext content of the region.

formattingPartial<RichtextFormatting>
Optional

The formatting of the region.

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
fontWeightFontWeight
Optional

The weight (thickness) of the font.

The available font weights depend on 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 text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRef
Optional

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

fontSizenumber
Optional

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.

Minimum: 1

Maximum: 100

textAlignstring
Optional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumber
Optional

The list indentation level of the paragraph.

listMarkerstring
Optional

The appearance of list item markers.

This property only has an effect if listLevel is greater than 0.

Default value: "none"

Available values:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"
rotationnumber
Optional

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Optional

Transparency as a percentage.

Minimum: 0

Maximum: 1

Returns

A state that creates a text element.

typestringRead-only

The type of content.

This must be "text".

textobjectRead-only

The text content.

regionsListState<TextRegion>

A list of items that can be read.

For more information, see ListState.

widthnumberRead-only

A width, in pixels.

heightnumberRead-only

A height, in pixels.

lockedbooleanRead-only

If true, the element is locked and cannot be modified.

topnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-only

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-only

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-only

Transparency as a percentage.

Minimum: 0

Maximum: 1

createRichtextRangefunction
Required

Creates a richtext range.

Returns

Provides methods for interacting with a range of formatted text.

formatParagraphfunction

Formats all of the paragraphs that overlap the given bounds.

  • The \n character indicates the end of a paragraph.
  • All paragraphs that overlap the provided bounds will be formatted in their entirety.

Parameters

boundsBounds
Required

The segment of the range on which to apply the formatting.

indexnumber
Required

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
Required

The number of characters in the segment, starting from the index.

formattingRichtextFormatting
Required

The formatting to apply to the paragraph(s).

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
fontWeightFontWeight
Optional

The weight (thickness) of the font.

The available font weights depend on 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 text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRef
Optional

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

fontSizenumber
Optional

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.

Minimum: 1

Maximum: 100

textAlignstring
Optional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumber
Optional

The list indentation level of the paragraph.

listMarkerstring
Optional

The appearance of list item markers.

This property only has an effect if listLevel is greater than 0.

Default value: "none"

Available values:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"

Returns

void

formatTextfunction

Formats a region of text with inline formatting properties.

Parameters

boundsBounds
Required

The segment of the range on which to apply the formatting.

indexnumber
Required

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
Required

The number of characters in the segment, starting from the index.

formattingInlineFormatting
Required

The formatting to apply to the text.

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
fontWeightFontWeight
Optional

The weight (thickness) of the font.

The available font weights depend on 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 text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunction

Appends the specified characters to the end of the range.

Parameters

charactersstring
Required

The characters to append to the richtext range.

formattingInlineFormatting
Optional

Options for formatting inline richtext.

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
fontWeightFontWeight
Optional

The weight (thickness) of the font.

The available font weights depend on 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 text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

A segment of a richtext range.

indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

replaceTextfunction

Replaces a region of text with the specified characters.

Parameters

boundsBounds
Required

The segment of the range to replace.

indexnumber
Required

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
Required

The number of characters in the segment, starting from the index.

charactersstring
Required

The replacement characters.

formattingInlineFormatting
Optional

The formatting to apply to the replaced text.

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
fontWeightFontWeight
Optional

The weight (thickness) of the font.

The available font weights depend on 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 text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

The bounds of the replacement characters within the updated range.

indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

readPlaintextfunction

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunction

Returns the current state of the richtext as one or more text regions. Each region is an object that contains the text content and its formatting.

Returns

textstring

The plaintext content of the region.

formattingPartial<RichtextFormatting>
Optional

The formatting of the region.

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
fontWeightFontWeight
Optional

The weight (thickness) of the font.

The available font weights depend on 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 text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRef
Optional

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

fontSizenumber
Optional

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.

Minimum: 1

Maximum: 100

textAlignstring
Optional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumber
Optional

The list indentation level of the paragraph.

listMarkerstring
Optional

The appearance of list item markers.

This property only has an effect if listLevel is greater than 0.

Default value: "none"

Available values:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"