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

ElementList

API reference for the ElementList type.

A list of elements.

Methods

countfunctionRequired

Gets the number of items in the list.

Returns

The number of items.

number

toArrayfunctionRequired

Converts the list to an array.

Returns

An array containing all items. The items are the same as in the list.

For more information, see AbsoluteElement.

forEachfunctionRequired

Executes a function for each item in the list.

Parameters

callbackForEachCallback<AbsoluteElement>Required

The function to run for each item.

For more information, see AbsoluteElement.

Parameters

itemAbsoluteElementRequired

The current item in the list.

For more information, see AbsoluteElement.

indexnumberRequired

The index of the current item.

Returns

void

Returns

void

filterfunctionRequired

Creates a new array with items that pass a test.

Parameters

filterFilterPredicate<AbsoluteElement>Required

A function that tests each item. Returns true to keep the item.

For more information, see AbsoluteElement.

Parameters

itemAbsoluteElementRequired

The item to test.

For more information, see AbsoluteElement.

Returns

true if the item should be included, otherwise false.

boolean

Returns

An array of items that passed the test.

For more information, see AbsoluteElement.

moveBeforefunctionRequired

Moves an existing item to a new position right before another item.

Parameters

refundefined | AbsoluteElementRequired

The existing item to move the item before. If ref is undefined, the item is moved to the end of the list. If ref does not exist in the list, the operation fails.

For more information, see AbsoluteElement.

itemAbsoluteElementRequired

The item to move. The operation fails if the item is not already in the list.

For more information, see AbsoluteElement.

Returns

void

moveAfterfunctionRequired

Moves an existing item to a new position right after another item.

Parameters

refundefined | AbsoluteElementRequired

The existing item to move the item after. If ref is undefined, the item is moved to the end of the list. If ref does not exist in the list, the operation fails.

For more information, see AbsoluteElement.

itemAbsoluteElementRequired

The item to move. The operation fails if the item is not already in the list.

For more information, see AbsoluteElement.

Returns

void

deletefunctionRequired

Removes an item from the list.

Parameters

itemAbsoluteElementRequired

The item to remove from the list.

For more information, see AbsoluteElement.

Returns

void

insertBeforefunctionRequired

Adds a copy of an item to the list and places it right before another item.

Parameters

refundefined | AbsoluteElementRequired

The existing item to place the new item before. If ref is undefined, the new item is added at the end of the list. If ref does not exist in the list, the operation fails.

For more information, see AbsoluteElement.

stateInsertableElementStateRequired

An element state that can be inserted into a page.

A state that creates a rectangle element.

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

typestringRead-onlyRequired

The type of content.

This must be "rect".

fillFillStateRead-onlyRequired

The appearance of the rectangle's interior.

mediaContainerundefined | MediaFillStateRequired

The media fill for the path, if any.

A state that creates an image fill.

typestringRead-onlyRequired

The type of media.

This must be "image".

imageRefImageRefRead-onlyRequired

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

flipXbooleanRequired

If true, the image is flipped horizontally.

flipYbooleanRequired

If true, the image is flipped vertically.

A state that creates a video fill.

typestringRead-onlyRequired

The type of media.

This must be "video".

videoRefVideoRefRead-onlyRequired

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

flipXbooleanRequired

If true, the video is flipped horizontally.

flipYbooleanRequired

If true, the video is flipped vertically.

colorContainerundefined | ColorFillStateRequired

The color fill for the path, if any.

A state that creates a solid color fill.

typestringRead-onlyRequired

The type of color.

This must be "solid".

colorstringRequired

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-onlyRequired

This must be "unsupported".

strokeStrokeStateRead-onlyRequired

The outline of the rectangle.

weightnumberRequired

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorContainerColorFillStateRequired

The color of the stroke.

A state that creates a solid color fill.

typestringRead-onlyRequired

The type of color.

This must be "solid".

colorstringRequired

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-onlyRequired

This must be "unsupported".

widthnumberRead-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

A state that creates a vector shape element.

typestringRead-onlyRequired

The type of content.

This must be "shape".

viewBoxAlignedBoxStateRead-onlyRequired

The scale and cropping of the shape.

topnumberRead-onlyRequired

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

leftnumberRead-onlyRequired

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

widthnumberRead-onlyRequired

The width of the view box, in pixels.

heightnumberRead-onlyRequired

The height of the view box, in pixels.

pathsListState<PathState>Read-onlyRequired

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-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

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

typestringRead-onlyRequired

The type of content.

This must be "embed".

urlstringRead-onlyRequired

The URL of the rich media.

This URL must be supported by the Iframely API.

widthnumberRead-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

A state that creates a text element.

typestringRead-onlyRequired

The type of content.

This must be "text".

textobjectRead-onlyRequired

The text content.

regionsListState<TextRegion>Required

A list of items that can be read.

For more information, see ListState.

widthnumberRead-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

Returns

The added item, or undefined if the operation failed.

For more information, see AbsoluteElement.

insertAfterfunctionRequired

Adds a copy of an item to the list and places it right after another item.

Parameters

refundefined | AbsoluteElementRequired

The existing item to place the new item after. If ref is undefined, the new item is added at the end of the list. If ref does not exist in the list, the operation fails.

For more information, see AbsoluteElement.

stateInsertableElementStateRequired

An element state that can be inserted into a page.

A state that creates a rectangle element.

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

typestringRead-onlyRequired

The type of content.

This must be "rect".

fillFillStateRead-onlyRequired

The appearance of the rectangle's interior.

mediaContainerundefined | MediaFillStateRequired

The media fill for the path, if any.

A state that creates an image fill.

typestringRead-onlyRequired

The type of media.

This must be "image".

imageRefImageRefRead-onlyRequired

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

flipXbooleanRequired

If true, the image is flipped horizontally.

flipYbooleanRequired

If true, the image is flipped vertically.

A state that creates a video fill.

typestringRead-onlyRequired

The type of media.

This must be "video".

videoRefVideoRefRead-onlyRequired

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

flipXbooleanRequired

If true, the video is flipped horizontally.

flipYbooleanRequired

If true, the video is flipped vertically.

colorContainerundefined | ColorFillStateRequired

The color fill for the path, if any.

A state that creates a solid color fill.

typestringRead-onlyRequired

The type of color.

This must be "solid".

colorstringRequired

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-onlyRequired

This must be "unsupported".

strokeStrokeStateRead-onlyRequired

The outline of the rectangle.

weightnumberRequired

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorContainerColorFillStateRequired

The color of the stroke.

A state that creates a solid color fill.

typestringRead-onlyRequired

The type of color.

This must be "solid".

colorstringRequired

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-onlyRequired

This must be "unsupported".

widthnumberRead-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

A state that creates a vector shape element.

typestringRead-onlyRequired

The type of content.

This must be "shape".

viewBoxAlignedBoxStateRead-onlyRequired

The scale and cropping of the shape.

topnumberRead-onlyRequired

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

leftnumberRead-onlyRequired

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

widthnumberRead-onlyRequired

The width of the view box, in pixels.

heightnumberRead-onlyRequired

The height of the view box, in pixels.

pathsListState<PathState>Read-onlyRequired

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-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

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

typestringRead-onlyRequired

The type of content.

This must be "embed".

urlstringRead-onlyRequired

The URL of the rich media.

This URL must be supported by the Iframely API.

widthnumberRead-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

A state that creates a text element.

typestringRead-onlyRequired

The type of content.

This must be "text".

textobjectRead-onlyRequired

The text content.

regionsListState<TextRegion>Required

A list of items that can be read.

For more information, see ListState.

widthnumberRead-onlyRequired

A width, in pixels.

heightnumberRead-onlyRequired

A height, in pixels.

lockedbooleanRead-onlyRequired

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

topnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRead-onlyRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRead-onlyRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRead-onlyRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

Returns

The added item, or undefined if the operation failed.

For more information, see AbsoluteElement.