initAppElement

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

Initializes an element that the app can edit once it exists in the user's design.

To learn more, see Creating app elements.

Usage

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

// The data structure to attach to the app element
type AppElementData = {
  text: string;
};

// Initialize the app element
const appElement = initAppElement<AppElementData>({
  render: (data) => {
    return [
      {
        type: "TEXT",
        children: [data.text],
        top: 0,
        left: 0,
      },
    ];
  },
});

// Set the app element data
appElement.addOrUpdateElement({
  text: "Hello world",
});

// Keep track of element changes
appElement.registerOnElementChange((element) => {
  console.log("The app element has changed:", element?.data);
});

Permissions

Before an app that uses this method can be submitted for review, the following permissions must be enabled via the Developer Portal:

canva:design:content:read, if the app calls the registerOnElementChange method
canva:design:content:write, if the app calls the addOrUpdateElement method

To learn more, see Configuring permissions.

Parameters

optionsobject

REQUIRED

The options for initializing an app element.

options.renderfunction

REQUIRED

Renders an app element based on the current state of the app element data.

This function must return an array of one or more elements, such as images or shapes, and all of the elements must have the following positional properties:

top
left
width
height

options.render(data)function

REQUIRED

The current state of the app element data.

Returns

A Promise that resolves with the following object:

resultobject

REQUIRED

The result of the successful initialization of an app element.

result.addOrUpdateElementfunction

REQUIRED

If an app element is not selected, sets the initial data of the element and adds it to the user's design. If an app element is selected, overwrites the data and re-renders the element.

result.addOrUpdateElement(data)object

REQUIRED

The data to attach to the app element.

result.addOrUpdateElement(data, placement)object

OPTIONAL

The position of the app element on the page.

result.addOrUpdateElement(data, placement.top)number

REQUIRED

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

result.addOrUpdateElement(data, placement.left)number

REQUIRED

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

result.addOrUpdateElement(data, placement.width)number

REQUIRED

The width of the element, in pixels.

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

result.addOrUpdateElement(data, placement.height)number

REQUIRED

The height of the element, in pixels.

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

result.addOrUpdateElement(data, placement.rotation)number

OPTIONAL

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

result.registerOnElementChangefunction

REQUIRED

Registers a callback that runs when the app element data or selection changes.

result.registerOnElementChange(callback)function

REQUIRED

The callback that runs when the app element data or selection changes.

result.registerOnElementChange(callback(element))object

OPTIONAL

The selected element. If an element is not selected, this is undefined.

result.registerOnElementChange(callback(element.data))object

REQUIRED

The current state of the app element data.

result.registerOnElementChange(callback(element.version))string

REQUIRED

The version number of the app.