Creating images

How to add images to a user's design.

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.

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

Apps can add the following types of images to a user's design:

NameMIME typeCommon file extensions
HEICimage/heic.heic
JPEGimage/jpeg.jpg, .jpeg
PNGimage/png.png
SVGimage/svg+xml.svg
WebPimage/webp.webp

The maximum file size for images is 25MB.

When creating images, the image data can be provided as a data URL or an external URL. The chosen format affects both the user and developer experience.

A data URL is a URI scheme that allows you to include data in-line in web pages as if they were external resources. For example, a data URL representation of a PNG image looks something like this:

data:image/png;base64,iVBORw0KGg...

To learn more, see the MDN documentation.

  • It's the most convenient way to generate images at runtime
  • There's less code required to create images from data URLs
  • The image data is downloaded via Canva's frontend, which is slower
  • In some cases, data URLs can increase an app's bundle size

An external URL is any URL that points to a file hosted on a third-party server. Generally speaking, we recommend that apps use external URLs as they offer the best user experience.

  • The image data is downloaded via Canva's backend, which is the fastest option
  • There's no risk of increasing the app's bundle size
  • Creating images from external URLs requires more code
  • There are strict requirements for external URLs

There are various ways for an app to create data URLs. This section explores a couple of the most common options: importing the images and using the Canvas API.

In the starter kit, images can be imported directly into the app's source code:

import dog from "../assets/dog.jpg";
console.log(dog); // => data:image/jpeg;base64,/9j/4AA...

The imported images are immediately available as data URLs.

This is suitable for small image files that must be loaded for most users, such as thumbnail images. The downside is that it increases the size of the JavaScript bundle, which increases the app's load time.

You can use the Canvas API to generate images from scratch or apply effects to existing images. For example, the following function returns a data URL for a gradient image:

function createGradient(color1: string, color2: string): string {
const canvas = document.createElement("canvas");
canvas.width = 640;
canvas.height = 360;
const ctx = canvas.getContext("2d");
if (!ctx) {
throw new Error("Can't get CanvasRenderingContext2D");
}
const gradient = ctx.createLinearGradient(0, 0, canvas.width, canvas.height);
gradient.addColorStop(0, color1);
gradient.addColorStop(1, color2);
ctx.fillStyle = gradient;
ctx.fillRect(0, 0, canvas.width, canvas.height);
return canvas.toDataURL();
}

Import the addNativeElement method from the @canva/design package:

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

Call the method, passing in the options shown here:

await addNativeElement({
type: "IMAGE",
dataUrl: createGradient("#ff0099", "#0000ff"),
});

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",
id: "uniqueidgoeshere",
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",
});

When uploading images:

  • The id property must contain a unique identifier that always points to the same file. This ensures that Canva doesn't upload duplicate files to the user's account.
  • 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.

Import the addNativeElement method from the @canva/design package:

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

Call the method, passing in the options shown here:

await addNativeElement({
type: "IMAGE",
ref: result.ref,
});
import React from "react";
import { addNativeElement } from "@canva/design";
export function App() {
async function handleClick() {
// Add the image to the design
await addNativeElement({
type: "IMAGE",
dataUrl: createGradient("#ff0099", "#0000ff"),
});
}
return (
<div>
<button onClick={handleClick}>Add image from data URL</button>
</div>
);
}
function createGradient(color1: string, color2: string): string {
const canvas = document.createElement("canvas");
canvas.width = 640;
canvas.height = 360;
const ctx = canvas.getContext("2d");
if (!ctx) {
throw new Error("Can't get CanvasRenderingContext2D");
}
const gradient = ctx.createLinearGradient(0, 0, canvas.width, canvas.height);
gradient.addColorStop(0, color1);
gradient.addColorStop(1, color2);
ctx.fillStyle = gradient;
ctx.fillRect(0, 0, canvas.width, canvas.height);
return canvas.toDataURL();
}
import React from "react";
import { upload } from "@canva/asset";
import { addNativeElement } from "@canva/design";
export function App() {
async function handleClick() {
// Upload an image
const result = await upload({
type: "IMAGE",
id: "uniqueidgoeshere",
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",
});
// Add the image to the design
await addNativeElement({
type: "IMAGE",
ref: result.ref,
});
}
return (
<div>
<button onClick={handleClick}>Add image from external URL</button>
</div>
);
}