> ## Documentation Index > Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt > Use this file to discover all available pages before exploring further. # initAppElement API reference for the initAppElement method. NOTE: **This 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. ## Usage ### Initialize app element client ```typescript import { initAppElement } from "@canva/design"; const appElement = initAppElement<{ content: string }>({ render: (data) => { return [{ type: 'text', children: [data.content], top: 100, left: 100, width: 200 }]; } }); ``` ### Initialize V2 app element client ```typescript import { initAppElement } from "@canva/design"; const appElement = initAppElement<{ content: string }>({ render: (data) => { return [{ type: 'text', children: [data.content], top: 100, left: 100, width: 200 }]; } }); ``` ## Parameters Configuration for an AppElementClient Properties of appElementConfig}> Registers a callback that renders an app element based on the data it receives. **Parameters** The data the callback must use to render the app element. A primitive data type that can be used in app element data. All primitive data types are supported except for symbols and bigints. An object primitive data type that can be used in app element data. **Returns** An array of one or more elements to render as output of an app element. `AppElementRendererOutput` ## Returns A client that provides methods for creating and managing the lifecycle of an app element. This type has been superseded, use `addElement` or `registerOnElementChange` instead. If an app element is selected, the element's data is overwritten and the element is re-rendered. Otherwise, the provided data is used to create a new app element. **Parameters** The data to attach to the app element. Existing data will be overwritten. A primitive data type that can be used in app element data. All primitive data types are supported except for symbols and bigints. An object primitive data type that can be used in app element data. The position, dimensions, and rotation of the app element. Properties of placement}> The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` **Returns** `Promise` **Examples** **Create or update an element (deprecated)** ```typescript import { initAppElement } from "@canva/design"; // Initialize the app element client const appElement = initAppElement<{ content: string; timestamp: number }>({ render: (data) => { return [{ type: 'text', children: [data.content || 'Default text'], top: 100, left: 100, width: 200 }]; } }); // Create a new element or update selected element await appElement.addOrUpdateElement({ content: 'Hello from the app', timestamp: Date.now() }); ``` **Update with specific placement (deprecated)** ```typescript import { initAppElement } from "@canva/design"; const appElement = initAppElement<{ content: string }>({ render: (data) => { return [{ type: 'text', children: [data.content || 'Default text'], top: 0, left: 0, width: 200 }]; } }); // Create or update with specific placement await appElement.addOrUpdateElement( { content: 'Positioned content' }, { top: 200, left: 200, width: 300, height: 100 } ); ``` Adds a new app element to the design. **Parameters** The data and placement of the app element. Properties of opts}> The data to attach to the app element. A primitive data type that can be used in app element data. All primitive data types are supported except for symbols and bigints. An object primitive data type that can be used in app element data. The position, dimensions, and rotation of the app element. Properties of placement}> The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` **Returns** `Promise` **Examples** **Add new element with data** ```typescript import { initAppElement } from "@canva/design"; const appElement = initAppElement<{ content: string; id: string }>({ render: (data) => { return [{ type: 'text', children: [data.content || 'Default text'], top: 0, left: 0, width: 200 }]; } }); // Add a new element await appElement.addElement({ data: { content: 'New element content', id: 'element-' + Date.now() } }); ``` **Add element with specific placement** ```typescript import { initAppElement } from "@canva/design"; const appElement = initAppElement<{ title: string; description: string; createdAt: number; }>({ render: (data) => { return [{ type: 'text', children: [data.title || 'Default title'], top: 0, left: 0, width: 300, fontWeight: 'bold', fontSize: 24 }, { type: 'text', children: [data.description || 'Default description'], top: 50, left: 0, width: 300 }]; } }); // Add element with specific placement await appElement.addElement({ data: { title: 'Element Title', description: 'This is a description of the element', createdAt: Date.now() }, placement: { top: 100, left: 100, width: 400, height: 150, rotation: 0 } }); ``` A callback that runs when: * the app element is created * the app element's data is updated * the user selects an existing app element **Parameters** The callback to run when the app element changes. **Parameters** Information about the app element that was changed. Properties of appElement}> The app element data in its most recent state. A primitive data type that can be used in app element data. All primitive data types are supported except for symbols and bigints. An object primitive data type that can be used in app element data. The version number of the app. Function to update the app element data. **Examples** **Update element data only** ```typescript if (element) { await element.update({ data: { ...element.data, content: 'Updated content', lastUpdated: Date.now() } }); } ``` **Update data and placement** ```typescript if (element) { await element.update({ data: { ...element.data, content: 'Positioned element' }, placement: { top: 200, left: 200, width: 300, height: 100 } }); } ``` **Add metadata to element** ```typescript if (element) { await element.update({ data: { ...element.data, metadata: { ...(element.data.metadata || {}), lastEdited: Date.now(), editCount: (element.data.metadata?.editCount || 0) + 1, }, }, }); } ``` **Parameters** The data and placement to update the app element with. Properties of opts}> The data to attach to the app element. A primitive data type that can be used in app element data. All primitive data types are supported except for symbols and bigints. An object primitive data type that can be used in app element data. The position, dimensions, and rotation of the app element. Properties of placement}> The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` **Returns** `Promise` **Returns** `void` **Returns** `void` **Examples** **Handle element selection and update** ```typescript import { initAppElement } from "@canva/design"; const appElement = initAppElement<{ content: string }>({ render: (data) => { return [{ type: 'text', children: [data.content || 'Default text'], top: 0, left: 0, width: 200 }]; } }); // Register a handler for element changes appElement.registerOnElementChange((element) => { if (element) { // Element is created or selected // Optionally update the element // element.update({ // data: { ...element.data, lastSelected: Date.now() } // }); } else { // No element is selected } }); ``` **Update element when selected** ```typescript import { initAppElement } from "@canva/design"; const appElement = initAppElement<{ content: string; metadata: { created: number; lastSelected: number }; }>({ render: (data) => { // Render based on data return [{ type: 'text', children: [data.content || ''], top: 0, left: 0, width: 200 }]; } }); // Update element when selected appElement.registerOnElementChange(async (element) => { if (element) { // Check if this is a newly created or a selected element const isNewElement = !element.data.metadata?.created; if (isNewElement) { // Update a new element with initial metadata await element.update({ data: { ...element.data, metadata: { created: Date.now(), lastSelected: Date.now() } } }); } else { // Update existing element's last selected time await element.update({ data: { ...element.data, metadata: { ...element.data.metadata, lastSelected: Date.now() } } }); } } }); ``` ## Permissions To use this method, the following permissions must be enabled for the app: * `canva:design:content:read`, if the app calls the `registerOnElementChange` method * `canva:design:content:write`, if the app calls the `addElement`, `addOrUpdateElement`, or `update` methods To learn more, see [Permissions](https://www.canva.dev/docs/apps/configuring-intents-permissions/). ## Rate limit This method has the following rate limits: * `addElement`: 15 requests every 10 seconds * `addOrUpdateElement`: 30 requests every 10 seconds * `update`: 30 requests every 10 seconds