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