Integrating with Canva

At its most basic, an app is a JavaScript file that runs inside an iframe. Canva embeds this iframe in the side panel of the Canva editor. The app can then render content inside the iframe and interact with the editor via APIs.

Canva injects APIs into the app's iframe. The app can then access these APIs via a number of methods. The TypeScript declarations for these methods are organized into a handful of npm packages.

The available packages include:

• @canva/asset
• @canva/design
• @canva/error
• @canva/platform
• @canva/user

Apps can use any combination of these packages and their methods to implement the app's behavior.

To use a method, import it from a package and call it with the required parameters. For example, the following code sample demonstrates how to use the requestExport method from the @canva/design package:

import { requestExport } from "@canva/design";

const response = await requestExport({
  acceptedFileTypes: ["png", "jpg"],
});

console.log(response); // { exportBlobs: [{ url: "https://example.com/image.png" }] }

You can find the complete list of methods and their parameters in the API reference section of the documentation.

To ensure we're developing the best possible APIs, we want to get them in the hands of developers sooner rather than later. We do this by releasing preview versions of the APIs that anyone can play around with.

Canva provides a preview of the APIs through the npm package registry⁠(opens in a new tab or window). You can install an available preview API package by using npm with the beta dist-tag. The following npm command demonstrates how to install the preview @canva/design package:

npm install @canva/design@beta

After installing the preview package, you can then import the preview methods you'd like to try:

import { addElementAtPoint } from "@canva/design";

If a preview method reaches a stable release, you can then install the latest package version, and continue using the method without changing the import declaration. Confirm your package version by running npm list, and checking for the beta tag:

npm list -a @canva/design@beta

├── @canva/[email protected]
├─┬ digital_asset_management@ -> ./examples/digital_asset_management
  └─┬ @canva/[email protected]
    └── @canva/[email protected]

A preview accessed through the beta dist-tag exposes new methods and modified versions of existing methods. They're documented alongside the stable APIs, but we make sure to highlight anything that's only available as a preview.

If you're planning on using a preview package, be aware that:

• Anything imported with the beta dist-tag package may experience breaking changes at short notice. You should not rely on the methods remaining available or continuing to behave in the same way.
• If an app depends on the preview package, it won't be approved for release during Canva's app review process. You'll have to wait for the API to be moved into one of the stable packages.

Apps have a lot of freedom within their iframes, but not total freedom.

In particular, these are the technical limitations that developers struggle with:

• The iframe has a Content Security Policy (CSP) that prevents certain resources, such as third-party scripts, from being loaded. To learn more, see Content Security Policy.
• The iframe has a Permission Policy⁠(opens in a new tab or window) that prevents apps from accessing certain browser features. The only feature allowed by this policy is writing data to the user's clipboard.
• If the app sends HTTP requests to a backend, the requests will fail unless the backend is configured to support Cross-Origin Resource Sharing (CORS). To learn more, see Using a backend and Cross-Origin Resource Sharing.
• The app doesn't have free-for-all access to the underlying document model. This means it can't freely read and write changes to the design. It can only use Canva's APIs, which expose a limited subset of controls.