onReady

API reference for the "onReady" method.

Registers a callback that runs when the extension loads. This callback receives a range of parameters for setting up the extension, such as URLs for downloading the user's image.

Notes

  • Even if an extension doesn't render rich controls, it must always call the updateControlPanel method in the onReady callback. The only exception to this rule is when an editing extension supports simple presets.

  • If the onReady callback takes longer than 10 seconds to resolve, it times out.

  • If you await on the remoteProcess method from the onReady callback, the onReady callback will likely time out.

  • If an editing extension supports presets:

    • The onReady callback runs immediately before the onPresetsRequest callback.

    • The onReady callback runs instead of the onPresetSelected callback when the user opens the extension by selecting a preset.

Usage

const canva = window.canva.init();
canva.onReady(async (opts) => {
console.log(opts);
});

Parameters

Name

Type

Required

Description

handler

ReadyHandler

Yes

The callback that runs when the extension has finished loading.

Returns

void

Types

ReadyHandler

The callback that runs when the extension loads.

Signature

(opts) => void

Parameters

Name

Type

Required

Description

opts

object

Yes

Information that Canva provides to the extension at startup.

opts.assets

Map<string, string>

Yes

Assets uploaded to the extension via the Developer Portal. The key is the file name of an asset. The value is URL of the asset.

opts.element

CanvaElement\<CanvaMedia | undefined>

Yes

Represents the element as it appears in the user's design.

opts.image (deprecated)

CanvaImageBlob

Yes

The user's image.

opts.localizedLabels

Map<string, LocalizedLabel>

Yes

Localized labels uploaded to the extension via the Developer Portal. The key is a language code, such as "en". The value is the localized label.

opts.page

object

Yes

The dimensions of the page that contain the user's image.

opts.page.height

number

Yes

The height of the page that contains the user's image, in pixels.

opts.page.width

number

Yes

The width of the page that contains the user's image, in pixels.

opts.previewSize (deprecated)

object

Yes

The dimensions of the iframe that contains the user's image.

opts.previewSize.height (deprecated)

number

Yes

The height of the iframe that contains the user's image, in pixels.

opts.previewSize.width(deprecated)

number

Yes

The width of the iframe that contains the user's image, in pixels.

opts.presetId

string

No

The ID of a preset. If undefined, render the user's image without a preset applied.

Returns

void

LocalizedLabel

Represents a localized label.

Properties

Name

Type

Required

Description

key

string

Yes

A unique ID for the localized label

value

string

Yes

The content of the localized label.

translatorNote

string

Yes

A note to assist with translating the localized label.