Canva Developers logo
API reference
API reference

initAppElement

API reference for the initAppElement method.

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);
});

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.

#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 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 page, in pixels.

#result.addOrUpdateElement(data, placement.left)number
Required

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

#result.addOrUpdateElement(data, placement.width)number
Required

The width of the element, in pixels.

#result.addOrUpdateElement(data, placement.height)number
Required

The height of the element, in pixels.

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