Creating images
Apps can add images to a user's design, such as PNG or SVG files. The user can then arrange and manipulate those images with the Canva tooling they've come to know and love.
The user experience
When an app adds an image to the user's design, the image file is uploaded to the user's media library.
The user's media library has a storage quota. If the user has a Canva Pro(opens in a new tab or window) account, their storage quota is 1TB. Otherwise, their storage quota is 5GB. If the user exceeds the storage quota, they'll see an error.
Once the image exists in the user's design, the image is indistinguishable from images added via Canva's built-in features. This means the user can manipulate the image in all the same ways, including:
- Adjusting the size, position, and rotation of the image
- Applying effects to the image
- Using the image as a background
- Animating the image — for example, having it fade in
Supported image types
Apps can add the following types of images to a user's design:
Name | MIME type | Common file extensions |
---|---|---|
HEIC | image/heic | .heic |
JPEG | image/jpeg | .jpg, .jpeg |
PNG | image/png | .png |
SVG | image/svg+xml | .svg |
TIFF | image/tiff | .tiff, .tif |
WebP | image/webp | .webp |
The maximum file size for images is 50MB.
GIFs are handled as videos, not images. To learn more, see Creating videos.
Data URLs vs. external URLs
When creating images, the image data can be provided as an external URL or a base64-encoded data URL. The ideal format of the data depends on the behavior of the app:
- If the app generates images in the browser, such as by drawing on a
HTMLCanvasElement
, then a base64-encoded data URL will be the fastest and easiest way to provide the image data. - If the app generates or serves images from a third-party server, as would be the case with generative AI apps, then an external URL would make the most sense.
How to create images
Step 1: Enable the required permissions
In the Developer Portal, enable the following permissions:
canva:design:content:write
canva:asset:private:write
In the future, the Apps SDK will throw an error if the required permissions are not enabled.
To learn more, see Configuring permissions.
Step 2: Upload an image
Import the upload
method from the @canva/asset
package:
import { upload } from "@canva/asset";
Call the method, passing in the options shown here:
const result = await upload({type: "image",mimeType: "image/jpeg",url: "https://www.canva.dev/example-assets/image-import/image.jpg",thumbnailUrl:"https://www.canva.dev/example-assets/image-import/thumbnail.jpg",aiDisclosure: "none",});
When uploading images, the URLs must be exposed via the internet and available to Canva's backend, as Canva needs access to the URLs to download them. This means you can't use localhost
URLs.
The upload
method returns an object that contains a ref
property:
console.log(result.ref);
This property contains a reference, which is a unique identifier that points to an image asset in Canva's backend. An app can use this reference to interact with the file — even while it's uploading.
Step 3: Add the image to the design
Import the addElementAtPoint
method (or addElementAtCursor
, depending on the current context) from the @canva/design
package:
import { addElementAtPoint } from "@canva/design";
Call the method, passing in the options shown here:
await addElementAtPoint({type: "image",ref: result.ref,});
Additional considerations
- All images must comply with Canva's Acceptable Use Policy(opens in a new tab or window).
- All images must comply with Canva's Upload formats and requirements(opens in a new tab or window).
API reference
Code sample
import React from "react";import { upload } from "@canva/asset";import { addElementAtPoint } from "@canva/design";export function App() {async function handleClick() {// Upload an imageconst result = await upload({type: "image",mimeType: "image/jpeg",url: "https://www.canva.dev/example-assets/image-import/image.jpg",thumbnailUrl:"https://www.canva.dev/example-assets/image-import/thumbnail.jpg",aiDisclosure: "none",});// Add the image to the designawait addElementAtPoint({type: "image",ref: result.ref,});}return (<div><button onClick={handleClick}>Add image from external URL</button></div>);}