Creating app elements

An app element is a group of one or more elements that apps can modify after it's added to a design. This allows apps to make their own custom elements and for elements to be re-editable in the app that created them.

This guide explains how to create app elements.

Step 1: Initialize the Design Interaction capability

Like all capabilities, Canva injects the Design Interaction capability into the app's iframe and attaches it to the window object:

console.log(window.canva.designInteraction);

To access the capability, import and call the getDesignInteraction function:

import { getDesignInteraction } from "@canva/design-interaction";
const designInteraction = getDesignInteraction();
console.log(designInteraction); // => DesignInteraction

This function:

• Throws an error if the capability is unavailable
• Provides type-safety when using TypeScript

Step 2: Register an app element renderer

An app element renderer is a callback function that is responsible for rendering the content of an app element.

To register an app element renderer, call the registerRenderAppElement method:

designInteraction.registerRenderAppElement(() => {
  return [
    {
      type: "EMBED",
      url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      width: 640,
      height: 360,
      top: 0,
      left: 0,
    },
  ];
});

If you're using React, the method must be called in a useEffect hook:

React.useEffect(() => {
  designInteraction.registerRenderAppElement(() => {
    return [
      {
        type: "EMBED",
        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        width: 640,
        height: 360,
        top: 0,
        left: 0,
      },
    ];
  });
}, [designInteraction]);

The method accepts a function that returns an array of one or more elements, such as embed or text elements.

Each element in the array:

• Must have a width and height
• Can have top and left positions
• Can have a rotation (in degrees)

By returning multiple elements, apps can create new types of elements. There are, however, some important nuances in regards to how elements are positioned. To learn more, see Combining elements.

Step 3: Render an app element

By itself, registering the app renderer callback doesn't render the app element. To render the element, the app must call the setAppElementData method:

designInteraction.setAppElementData({});

This method attaches data the app element and passes that data into the app element renderer. This is a key feature of app elements that is beyond the scope of this guide. To learn more, see Setting app element data.

Passing an empty object into the setAppElementData method triggers the initial render, but re-renders can only be triggered by changing the data. Canva won't re-render the element if the data is the same.

Example

import React from "react";
import { getDesignInteraction } from "@canva/design-interaction";

export const App = () => {
  const designInteraction = getDesignInteraction();

  React.useEffect(() => {
    designInteraction.registerRenderAppElement(() => {
      return [
        {
          type: "EMBED",
          url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
          width: 640,
          height: 360,
          top: 0,
          left: 0,
        },
      ];
    });
  }, [designInteraction]);

  const handleClick = () => {
    designInteraction.setAppElementData({});
  };

  return (
    <div>
      <button onClick={handleClick}>Create app element</button>
    </div>
  );
};