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 elementtype AppElementData = {text: string;};// Initialize the app elementconst appElement = initAppElement<AppElementData>({render: (data) => {return [{type: "TEXT",children: [data.text],top: 0,left: 0,},];},});// Set the app element dataappElement.addOrUpdateElement({text: "Hello world",});// Keep track of element changesappElement.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 theregisterOnElementChange
methodcanva:design:content:write
, if the app calls theaddOrUpdateElement
method
To learn more, see Configuring permissions.
Parameters
The options for initializing an app element.
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
The current state of the app element data.
Returns
A Promise
that resolves with the following object:
The result of the successful initialization of an app element.
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.
The data to attach to the app element.
The position of the app element on the page.
The distance from the top edge of the page, in pixels.
The distance from the left edge of the page, in pixels.
The width of the element, in pixels.
If height
is a number, this can be set to "auto"
.
The height of the element, in pixels.
If width
is a number, this can be set to "auto"
.
The rotation of the element, in degrees. This must be a number between -180
and 180
.
Registers a callback that runs when the app element data or selection changes.
The callback that runs when the app element data or selection changes.
The selected element. If an element is not selected, this is undefined
.
The current state of the app element data.
The version number of the app.