Canva Button

Power your platform so your customers can design a

Canva Button

Power your platform so your customers can design a

Working with the Canva Button JS API

If you're not able to use the Canva Button HTML snippet — for example if your pages are rendered dynamically via React, Angular or a similar framework or library — then you will need to render the Button using HTML and CSS yourself, and then hook it up with Canva Button API.

First we will take a look at how to work with the Canva Button API, and then how to style it.

Step 1: Load the Canva Button SDK Script

The first step in using the Canva Button API is to load the SDK script. You can either load it dynamically or statically depending on how your website or application is built.

Dynamic script loading:

1
2
3
4
5
6
7
8
(function (document, url) {
var script = document.createElement('script');
script.src = url;
script.onload = function () {
// API initialization
};
document.body.appendChild(script);
})(document, 'https://sdk.canva.com/designbutton/v2/api.js');

Static script loading:

1
<script src="https://sdk.canva.com/designbutton/v2/api.js"></script>

Step 2: Initialize the Canva Button API

After script loading is taken care of, you can initialize the SDK and use the api object immediately or save it for future use.

The initialize() method should not be called multiple times on the same page. Once initialized, the same API instance can call createDesign() or editDesign() multiple times.

Initializing using ES6 and await/async:

1
2
3
4
5
6
7
8
(async function () {
if (window.Canva && window.Canva.DesignButton) {
const api = await window.Canva.DesignButton.initialize({
apiKey: 'YOUR-UNIQUE-API-KEY-HERE',
});
// Use "api" object or save for later
}
})();

Initializing using ES5 and promise:

1
2
3
4
5
6
7
8
9
(function () {
if (window.Canva && window.Canva.DesignButton) {
window.Canva.DesignButton.initialize({
apiKey: 'YOUR-UNIQUE-API-KEY-HERE',
}).then(function (api) {
// Use "api" object or save for later
});
}
})();

Step 3: Use the initialized API object

Finally, after getting a hold of the initialized api object you are now able to launch the Canva Editor. You may choose to trigger this action via a button on your page, or based on other events or flows in your app.

Use createDesign() to launch Canva editor with an empty design, and editDesign() to launch the Canva Editor with a previously created design.

Use createDesign() to launch the Editor with the specified parameters:

Use createDesign() to launch the Editor with the specified parameters:

ParameterTypeDescription
opts.design.typeString, requiredThe type of design you want your users to create. One of: A4Document, Announcement, BirthdayCard, BirthdayInvitation, BlogBanner, BookCover, Bookmark, Brochure, BusinessCard, Calendar, Card, Certificate, DesktopWallpaper, EmailHeader, EtsyShopCover, EtsyShopIcon, FacebookAd, FacebookAppAd, FacebookCover, FacebookEventCover, FacebookPost, Flyer, GiftCertificate, Infographic, InstagramPost, InstagramStory, Invitation, Invoice, Label, LargeRectangleAd, LeaderboardAd, LessonPlan, Letter, LinkedInBanner, Logo, MagazineCover, MediumRectangleAd, Menu, MindMap, Newsletter, PhotoCollage, PinterestGraphic, Postcard, Poster, Presentation, Presentation43, ProductLabel, RecipeCard, Resume, SnapchatGeofilter, SocialMedia, Ticket, TumblrGraphic, TwitterHeader, TwitterPost, WattpadBookCover, WeddingInvitation, WideSkyscraperAd, Worksheet, Yearbook, YouTubeChannelArt, YouTubeThumbnail
opts.design.dimensions.unitsString, optionalThe unit of opts.design.dimensions.width and opts.design.dimensions.height. One of: px (default), cm, in, mm
opts.design.dimensions.widthNumber, optionalThe width of the design, must specify either both height and width, or neither. For px units: 40–5000, for cm: 1.06–134, for mm: 10.6–1340, for in: 0.42–52
opts.design.dimensions.heightNumber, optionalThe height of the design, must specify either both height and width, or neither. For px units: 40–5000, for cm: 1.06–134, for mm: 10.6–1340, for in: 0.42–52
opts.editor.publishLabelString, optionalIf assigned, the given text will replace the word "Publish" in the upper right corner of the Canva Editor page.
opts.editor.fileTypeString, optionalThe file type to be used for the exported design. One of: png (default), pdf, jpeg or jpg.
opts.onDesignOpenFunction, optionalRegisters a JavaScript callback function that will be executed when the editor opens with an empty design.
opts.onDesignPublishFunction, optionalRegisters a JavaScript callback function that will be executed when the user completes their design.
opts.onDesignCloseFunction, optionalRegisters a JavaScript callback function that will be executed when the user closes the editor.

Use editDesign() to open an existing design by its ID:

ParameterTypeDescription
opts.design.idString, requiredThe ID of the existing design you want your user to edit.
opts.editor.publishLabelString, optionalIf assigned, the given text will replace the word "Publish" in the upper right corner of the Canva Editor page.
opts.editor.fileTypeString, optionalThe file type to be used for the exported design. One of: png (default), pdf, jpeg or jpg.
opts.onDesignOpenFunction, optionalRegisters a JavaScript callback function that will be executed when the Canva Editor opens the requested design.
opts.onDesignPublishFunction, optionalRegisters a JavaScript callback function that will be executed when the user finishes editing their design.
opts.onDesignCloseFunction, optionalRegisters a JavaScript callback function that will be executed when the user closes the editor.

Example usage in ES6:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
api.createDesign({
design: {
type: 'Poster',
},
onDesignOpen: ({ designId }) => {
// Triggered when editor finishes loading and opens a new design.
// You can save designId for future use.
},
onDesignPublish: ({ exportUrl, designId }) => {
// Triggered when design is published to an image.
// Save the image to your server as the exportUrl will expire shortly.
},
onDesignClose: () => {
// Triggered when editor is closed.
},
});

Example usage in ES5:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
api.createDesign({
design: {
type: 'Poster',
},
onDesignOpen: function (options) {
// Triggered when editor finishes loading and opens a new design.
var designId = options.designId;
// You can save designId for future use.
},
onDesignPublish: function (options) {
// Triggered when design is published to an image.
var exportUrl = options.exportUrl;
var designId = options.designId;
// Save the image to your server as the exportUrl will expire shortly.
},
onDesignClose: function () {
// Triggered when editor is closed.
},
});

Canva Editor callbacks

Having set callback method names through either createDesign() or editDesign(), these methods will now receive an object with the following parameters:
· exportUrl
· designId

ParameterTypeDescription
exportUrlString, requiredThe URL of the image you get back from the Canva editor. Should immediately be downloaded onto your server so that is ultimately served from your application.

String is received by onDesignPublish only.
designIdString, requiredThe ID of the created design can be saved to allow for later editing of the design.

Example of callback handling using ES6:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
api.createDesign({
design: {
type: 'Poster',
},
onDesignOpen: ({ designId }) => {
// Triggered when editor finishes loading and opens a new design.
// You can save designId for future use.
},
onDesignPublish: ({ exportUrl, designId }) => {
// Triggered when design is published to an image.
// Save the image to your server as the exportUrl will expire shortly.
},
onDesignClose: () => {
// Triggered when editor is closed.
},
});

API definition

Within your application, you may wish to define the expected shape of the returned Canva Button API. Here is a definition of all supported methods and parameters.

Here is a TypeScript-based declaration of the shape of the Canva Button API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
type CanvaButtonApi = {
createDesign: (opts: {
design: {
type: string,
dimensions?: {
width: number,
height: number,
units?: 'px' | 'cm' | 'mm' | 'in',
},
},
editor?: {
publishLabel?: string,
fileType?: 'jpg' | 'jpeg' | 'pdf' | 'png',
},
onDesignOpen?: (opts: { designId: string }) => void,
onDesignPublish?: (opts: { exportUrl: string, designId: string }) => void,
onDesignClose?: () => void,
}) => void;
editDesign: (opts: {
design: {
id: string,
},
editor?: {
publishLabel?: string,
fileType?: 'jpg' | 'jpeg' | 'pdf' | 'png',
},
onDesignOpen?: (opts: { designId: string }) => void,
onDesignPublish?: (opts: { exportUrl: string, designId: string }) => void,
onDesignClose?: () => void,
}) => void;
};
declare interface Window {
Canva: {
DesignButton: {
initialize: (opts: { apiKey: string }) => Promise<CanvaButtonApi>;
}
};
}

Styling your Button

This guide explains how the Button ideally should look if you’re building it from scratch. The following sections detail different aspects of the Button look and feel that you are advised to follow.

To speed things up, you can look at example HTML and CSS on https://codepen.io/cathywise/pen/zYBmoow. You can also use the “Build your Button” page as an inspiration for the CSS code.

Font styles

Use Open Sans font for the Button. If your page does not use Open Sans, you can add it to your page using Google Fonts, just make sure to include both regular and semi-bold font weights. If your website uses non-Latin characters (e.g. Cyrillic), don’t forget to add them on the Google Fonts page.

For all button sizes except for tiny (read more about size variants below), please use the semi-bold font weight. For the tiny size variation, please use the regular font-weight (font-weight: normal in CSS).

An example of the recommended font styles:

1
2
3
4
5
6
.canva-design-button {
font-family: 'Open Sans', sans-serif;
font-size: 16px;
font-weight: 600;
line-height: 1.6;
}

Themes and sizes

You are welcome to style the Button in line with the look and feel of your website, but it is strongly recommended to stay close to the proposed sizes and colors described here. They cover a wide enough range of use cases to look unobtrusive while retaining the unique and familiar Canva style.

There are three recommended themes to choose from:
· default (brand),
· dark and
· light.

For Button sizing, there are four recommended options:
· default (normal),
· large,
· small and
· tiny.

Button text

If the type of design that users will create with the Button is implied by its surroundings (header, graphics), then we recommend using default text: “Design on Canva.”

Using a longer call to action will give your users more context, just start the label with “Design” or “Create”. Examples:
· Design an invitation
· Create your business card
· Create a cover photo for your property
· Design your logo

Using the Canva logo

The type of Canva logo to be used in the Button depends on the theme you choose for the Button (themes were described in the previous section).

Please use the logo files provided here in SVG and PNG formats - they are tailored to the different themes and sizes shown above.