Appearance
Apps SDK — Asset API
Asset Upload
API reference for the upload method.
Uploads an asset to the user's private media library.
Usage
Upload an image from a URL
typescript
import { upload } from "@canva/asset";
await upload({
type: "image",
url: "https://example.com/image.jpg",
mimeType: "image/jpeg",
thumbnailUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none"
});Upload an image from a data URL
typescript
import { upload } from "@canva/asset";
await upload({
type: "image",
url: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
mimeType: "image/jpeg",
thumbnailUrl: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
aiDisclosure: "none"
});Upload a video from a URL
typescript
import { upload } from "@canva/asset";
await upload({
type: "video",
url: "https://example.com/video.mp4",
mimeType: "video/mp4",
thumbnailImageUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none"
});Upload an audio file from a URL
typescript
import { upload } from "@canva/asset";
await upload({
type: "audio",
url: "https://example.com/audio.mp3",
mimeType: "audio/mp3",
title: "My Audio",
durationMs: 30000,
aiDisclosure: "none"
});Upload a Lottie animation from a URL
typescript
import { upload } from "@canva/asset";
await upload({
type: "video",
url: "https://example.com/animation.json",
mimeType: "application/json",
thumbnailImageUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none"
});Upload an asset with dimensions (image and video only)
typescript
import { upload } from "@canva/asset";
await upload({
type: "image",
url: "https://example.com/image.jpg",
mimeType: "image/jpeg",
thumbnailUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none",
width: 1920,
height: 1080
});Upload an AI-generated asset
typescript
import { upload } from "@canva/asset";
await upload({
type: "image",
url: "https://example.com/ai-image.jpg",
mimeType: "image/jpeg",
thumbnailUrl: "https://example.com/thumb.jpg",
aiDisclosure: "app_generated"
});Upload an image with a custom name
typescript
import { upload } from "@canva/asset";
await upload({
type: "image",
name: "My Vacation Photo",
url: "https://example.com/image.jpg",
mimeType: "image/jpeg",
thumbnailUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none"
});Upload a video with a custom name
typescript
import { upload } from "@canva/asset";
await upload({
type: "video",
name: "Product Demo",
url: "https://example.com/video.mp4",
mimeType: "video/mp4",
thumbnailImageUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none"
});Wait for an asset to finish uploading
typescript
import { upload } from "@canva/asset";
// Start uploading the asset
const asset = await upload({
type: "video",
url: "https://example.com/video.mp4",
mimeType: "video/mp4",
thumbnailImageUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none"
});
// Wait for the upload to complete
await asset.whenUploaded();Parameters
<Prop.List> <Prop name="options" required type="AssetUploadOptions" sourceLineNumbers={[1035]}> Options for uploading an asset to the user's private media library.
<Tabs>
<Tab name="Images">
Options for uploading an image asset to the user's private media library.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[490]}>
The type of asset.
The only valid value is `"image"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[581]}>
The URL of the image file to upload.
This can be an external URL or a data URL.
Requirements for external URLs:
* Must use HTTPS
* Must return a `200` status code
* `Content-Type` must match the file's MIME type
* Must be publicly accessible (i.e. not a localhost URL)
* Must not redirect
* Must not contain an IP address
* Maximum length: 4096 characters
* Must not contain whitespace
* Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
* Maximum file size: 50MB
Requirements for data URLs:
* Must include `;base64` for base64-encoded data
* Maximum size: 10MB (10 × 1024 × 1024 characters)
Requirements for SVGs:
* Disallowed elements:
* `a`
* `altglyph`
* `altglyphdef`
* `altglyphitem`
* `animate`
* `animatemotion`
* `animatetransform`
* `cursor`
* `discard`
* `font`
* `font-face`
* `font-face-format`
* `font-face-name`
* `font-face-src`
* `font-face-uri`
* `foreignobject`
* `glyph`
* `glyphref`
* `missing-glyph`
* `mpath`
* `script`
* `set`
* `switch`
* `tref`
* Disallowed attributes:
* `crossorigin`
* `lang`
* `media`
* `onload`
* `ping`
* `referrerpolicy`
* `rel`
* `rendering-intent`
* `requiredextensions`
* `requiredfeatures`
* `systemlanguage`
* `tabindex`
* `transform-origin`
* `unicode`
* `vector-effect`
* The `href` attribute of an `image` element only supports data URLs for PNG and JPEG images.
* The URL in the `href` attribute must not point to a location outside of the SVG.
* The `style` attribute must not use the `mix-blend-mode` property.
</Prop>
<Prop name="mimeType" required type="ImageMimeType" sourceLineNumbers={[585]}>
The MIME type of the image file.
<Prop.Extras>
**Available values**:
* `"image/jpeg"`
* `"image/heic"`
* `"image/png"`
* `"image/svg+xml"`
* `"image/webp"`
* `"image/tiff"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[603]}>
The URL of a thumbnail image to display while the image is queued for upload.
This can be an external URL or a data URL.
Requirements for external URLs:
* Must use HTTPS
* Must support Cross-Origin Resource Sharing
* Must be a PNG, JPEG, or SVG file
* Maximum length: 4096 characters
Requirements for data URLs:
* Must include `;base64` for base64-encoded data
* Maximum size: 10MB (10 × 1024 × 1024 characters)
</Prop>
<Prop name="aiDisclosure" required type="AiDisclosure" sourceLineNumbers={[643]}>
A disclosure identifying if the app generated this image using AI
Helps users make informed decisions about the content they interact with.
See AiDisclosure for the full definition.
**App Generated**
'app\_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
the app requests a third-party service to take similar action on an image using AI.
Required for the following cases (this list is not exhaustive):
| Case | Reason |
| --------------------------------------------------------------- | ------------------------------------ |
| AI generates a new image from scratch | Creates new creative content |
| AI changes the style of the image e.g. makes it cartoon | Significantly alters the style |
| AI removes an object and replaces it with new content | Creates new creative content |
| AI changes the facial expression of a person in an image | Can alter content's original meaning |
| AI composites multiple images together | Significantly alters context |
| AI expands an image by generating new content to fill the edges | Creates new creative content |
| AI replaces background by generating new content | Creates new creative content |
**None**
'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request
to third-party hosted content.
Required for the following cases (this list is not exhaustive):
| Case | Reason |
| -------------------------------------------------- | ----------------------------------------- |
| Asset comes from an asset library | Didn't generate the asset itself |
| AI corrects red eyes | A minor correction |
| AI removes background without replacement | Doesn't change original meaning by itself |
| AI changes the color of an object in an image | Doesn't change original meaning by itself |
| AI detects image defects and suggests manual fixes | Didn't change the asset itself |
| AI adjusts brightness and contrast on an image | Doesn't change original meaning by itself |
| AI upscales an image | Doesn't change original meaning by itself |
<Prop.Extras>
**Available values**:
* `"app_generated"`
* `"none"`
</Prop.Extras>
</Prop>
<Prop name="name" type="string" sourceLineNumbers={[503]}>
A human-readable name for the image asset.
This name is displayed in the user's media library and helps users identify
and find the asset later. If not provided, Canva will generate a name based
on the asset's URL or a unique identifier.
Requirements:
* Minimum length: 1 character (empty strings are not allowed)
* Maximum length: 255 characters
</Prop>
<Prop name="parentRef" type="ImageRef" sourceLineNumbers={[510]}>
The ref of the original asset from which this new asset was derived.
For example, if an app applies an effect to an image, `parentRef` should contain the ref of the original image.
</Prop>
<Prop name="width" required="When `height` is defined" type="number" sourceLineNumbers={[241]}>
A width, in pixels.
</Prop>
<Prop name="height" required="When `width` is defined" type="number" sourceLineNumbers={[245]}>
A height, in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
Options for uploading a video asset to the user's private media library.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1064]}>
The type of asset.
The only valid value is `"video"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[1102]}>
The URL of the video file to upload.
Requirements:
* Must use HTTPS
* Must return a `200` status code
* `Content-Type` must match the file's MIME type
* Must be publicly accessible (i.e. not a localhost URL)
* Must not redirect
* Must not contain an IP address
* Maximum length: 4096 characters
* Must not contain whitespace
* Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
* Maximum file size: 1000MB (1GB)
</Prop>
<Prop name="mimeType" required type="VideoMimeType" sourceLineNumbers={[1106]}>
The MIME type of the video file.
<Prop.Extras>
**Available values**:
* `"video/avi"`
* `"video/x-msvideo"`
* `"image/gif"`
* `"video/x-m4v"`
* `"video/x-matroska"`
* `"video/quicktime"`
* `"video/mp4"`
* `"video/mpeg"`
* `"video/webm"`
* `"application/json"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailImageUrl" required type="string" sourceLineNumbers={[1138]}>
The URL of a thumbnail image to use as a fallback if `thumbnailVideoUrl` isn't provided.
This can be an external URL or a data URL.
Requirements for external URLs:
* Must use HTTPS
* Must support Cross-Origin Resource Sharing
* Must be a PNG, JPEG, or SVG file
* Maximum length: 4096 characters
Requirements for data URLs:
* Must include `;base64` for base64-encoded data
* Maximum size: 10MB (10 × 1024 × 1024 characters)
* The dimensions of the thumbnail must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
</Prop>
<Prop name="aiDisclosure" required type="AiDisclosure" sourceLineNumbers={[1176]}>
A disclosure identifying if the app generated this video using AI.
Helps users make informed decisions about the content they interact with.
See AiDisclosure for the full definition.
**App Generated**
'app\_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
the app requests a third-party service to take similar action on a video using AI.
Required for the following cases (this list is not exhaustive):
| Case | Reason |
| -------------------------------------------------------------- | ------------------------------ |
| AI generates a new video from scratch | Creates new creative content |
| AI changes the style of the video e.g. makes it cartoon | Significantly alters the style |
| AI adds subtitles that rely on subjective interpretation | Creates new creative content |
| AI expands a video by generating new content to fill the edges | Creates new creative content |
| AI animates an image | Creates new creative content |
| AI fixes defects e.g. blur in a video by generating details | Creates new creative content |
| AI generates a talking head presenter | Creates new creative content |
**None**
'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of
a request to third-party hosted content.
Required for the following cases (this list is not exhaustive):
| Case | Reason |
| -------------------------------------------------------- | ----------------------------------------- |
| Asset comes from an asset library | Didn't generate the asset itself |
| AI corrects red eyes | A minor correction |
| AI adjusts brightness and contrast on a video | Doesn't change original meaning by itself |
| AI creates a slow motion effect in a video | Doesn't change original meaning by itself |
| AI adds AI word-by-word transcribed subtitles to a video | Doesn't change original meaning by itself |
<Prop.Extras>
**Available values**:
* `"app_generated"`
* `"none"`
</Prop.Extras>
</Prop>
<Prop name="name" type="string" sourceLineNumbers={[1077]}>
A human-readable name for the video asset.
This name is displayed in the user's media library and helps users identify
and find the asset later. If not provided, Canva will generate a name based
on the asset's URL or a unique identifier.
Requirements:
* Minimum length: 1 character (empty strings are not allowed)
* Maximum length: 255 characters
</Prop>
<Prop name="parentRef" type="VideoRef" sourceLineNumbers={[1084]}>
The ref of the original asset from which this new asset was derived.
For example, if an app applies an effect to a video, `parentRef` should contain the ref of the original video.
</Prop>
<Prop name="thumbnailVideoUrl" type="string" sourceLineNumbers={[1119]}>
The URL of a thumbnail video to display while the video is queued for upload.
Requirements:
* Must use HTTPS
* Must support Cross-Origin Resource Sharing
* Maximum length: 4096 characters
* The dimensions of the thumbnail video must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
* Must not be an AVI file. Although our APIs support uploading AVI videos, Canva can't preview them because of native support of browsers
</Prop>
<Prop name="width" required="When `height` is defined" type="number" sourceLineNumbers={[241]}>
A width, in pixels.
</Prop>
<Prop name="height" required="When `width` is defined" type="number" sourceLineNumbers={[245]}>
A height, in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="Audio">
Options for uploading an audio asset to the user's private media library.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[92]}>
The type of asset.
The only valid value is `"audio"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[110]}>
The URL of the audio file to upload to the user's private media library.
Requirements:
* Must use HTTPS
* Must return a `200` status code
* `Content-Type` must match the file's MIME type
* Must be publicly accessible (i.e. not a localhost URL)
* Must not redirect
* Must not contain an IP address
* Maximum length: 4096 characters
* Must not contain whitespace
* Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
* Maximum file size: 250MB
</Prop>
<Prop name="mimeType" required type="AudioMimeType" sourceLineNumbers={[114]}>
The MIME type of the audio file.
<Prop.Extras>
**Available values**:
* `"audio/mpeg"`
* `"audio/mp4"`
* `"audio/x-m4a"`
* `"audio/mp3"`
* `"audio/ogg"`
* `"audio/wav"`
* `"audio/x-wav"`
* `"audio/wave"`
* `"audio/vnd.wave"`
* `"audio/x-pn-wav"`
* `"audio/webm"`
</Prop.Extras>
</Prop>
<Prop name="title" required type="string" sourceLineNumbers={[121]}>
A human-readable title for the audio asset.
This title is displayed in the Canva editor.
</Prop>
<Prop name="durationMs" required type="number" sourceLineNumbers={[125]}>
The initial playback duration of the audio file, in milliseconds.
</Prop>
<Prop name="aiDisclosure" required type="AiDisclosure" sourceLineNumbers={[158]}>
A disclosure identifying if the app generated this audio using AI.
Helps users make informed decisions about the content they interact with.
See AiDisclosure for the full definition.
**App Generated**
'app\_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
the app requests a third-party service to take similar action on an audio asset using AI.
Required for the following cases (this list is not exhaustive):
| Case | Reason |
| --------------------------------------------------- | ---------------------------- |
| AI generates a music track from scratch | Creates new creative content |
| AI generates sounds from scratch e.g. animal sounds | Creates new creative content |
| AI converts text to speech | Creates new creative content |
| AI changes the mood or genre of audio/music | Significantly alters context |
| AI adjusts pitch or tempo for a creative purpose | Significantly alters context |
**None**
'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to
third-party hosted content.
Required for the following cases (this list is not exhaustive):
| Case | Reason |
| --------------------------------- | -------------------------------- |
| Asset comes from an asset library | Didn't generate the asset itself |
| AI balances audio across speakers | A minor correction |
<Prop.Extras>
**Available values**:
* `"app_generated"`
* `"none"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
An asset that's queued for upload to the user's private media library. This is a Promise that resolves with the following object:
<Tabs> <Tab name="Images"> An image asset that's queued for upload to the user's private media library.
<Prop.List>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[758]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="whenUploaded" required readonly type="function" sourceLineNumbers={[762]}>
Returns a `Promise` that resolves when the asset has finished uploading.
**Returns**
`Promise<void>`
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos"> A video asset that's queued for upload to the user's private media library.
<Prop.List>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[773]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="whenUploaded" required readonly type="function" sourceLineNumbers={[777]}>
Returns a `Promise` that resolves when the asset has finished uploading.
**Returns**
`Promise<void>`
</Prop>
</Prop.List>
</Tab>
<Tab name="Audio"> An audio asset that's queued for upload to the user's private media library.
<Prop.List>
<Prop name="ref" required type="AudioRef" sourceLineNumbers={[743]}>
A unique identifier that points to the audio asset in Canva's backend.
</Prop>
<Prop name="whenUploaded" required readonly type="function" sourceLineNumbers={[747]}>
Returns a `Promise` that resolves when the asset has finished uploading.
**Returns**
`Promise<void>`
</Prop>
</Prop.List>
</Tab> </Tabs>
Get Temporary URL
API reference for the getTemporaryUrl method.
Retrieves a temporary URL that points to an asset in Canva's backend.
Usage
Get the URL of an uploaded image asset
typescript
import { type ImageRef, getTemporaryUrl } from "@canva/asset";
const placeholderImageRef = "PLACEHOLDER_IMAGE_REF" as ImageRef;
const result = await getTemporaryUrl({
type: "image",
ref: placeholderImageRef
});Get the URL of an uploaded video asset
typescript
import { type VideoRef, getTemporaryUrl } from "@canva/asset";
const placeholderVideoRef = "PLACEHOLDER_VIDEO_REF" as VideoRef;
const result = await getTemporaryUrl({
type: "video",
ref: placeholderVideoRef
});Parameters
<Prop.List> <Prop name="options" required type="GetTemporaryUrlOptions" sourceLineNumbers={[429]}> Options for retrieving a temporary URL that points to an asset in Canva's backend.
<Tabs>
<Tab name="Images">
Options for retrieving a temporary URL that points to an image asset in Canva's backend.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[440]}>
The type of asset.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[444]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
Options for retrieving a temporary URL that points to a video asset in Canva's backend.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[455]}>
The type of asset.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[459]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
The result of retrieving a temporary URL of an asset in Canva's backend. This is a Promise that resolves with the following object:
<Tabs> <Tab name="Images"> The result of retrieving a temporary URL of an image asset in Canva's backend.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[858]}>
The type of asset.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[862]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[866]}>
A temporary URL for downloading the asset.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos"> The result of retrieving a temporary URL of a video asset in Canva's backend.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[877]}>
The type of asset.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[881]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[885]}>
A temporary URL for downloading the asset.
</Prop>
</Prop.List>
</Tab> </Tabs>
Find Fonts
API reference for the findFonts method.
Retrieves a list of fonts.
Only a subset of Canva's fonts are returned.
Usage
Get a list of all available fonts
typescript
import { findFonts } from "@canva/asset";
const response = await findFonts();Get a specific font
typescript
import { type FontRef, findFonts } from "@canva/asset";
const placeholderFontRef = "PLACEHOLDER_FONT_REF" as FontRef;
const response = await findFonts({
fontRefs: [placeholderFontRef]
});Get multiple specific fonts
typescript
import { type FontRef, findFonts } from "@canva/asset";
const placeholderFontRef1 = "PLACEHOLDER_FONT_REF" as FontRef;
const placeholderFontRef2 = "PLACEHOLDER_FONT_REF" as FontRef;
const response = await findFonts({
fontRefs: [placeholderFontRef1, placeholderFontRef2]
});Parameters
<Prop.List> <Prop name="options" type="FindFontsOptions" sourceLineNumbers={[285]}> Options for retrieving a list of fonts.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="fontRefs" type="FontRef[]" sourceLineNumbers={[295]}>
The refs of the fonts to retrieve.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
The result of retrieving a list of fonts. This is a Promise that resolves with the following object:
<Prop.List> <Prop name="fonts" required type="Font[]" sourceLineNumbers={[306]}> The retrieved fonts.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fonts</strong></>}>
<Prop.List>
<Prop name="ref" required type="FontRef" sourceLineNumbers={[317]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="name" required type="string" sourceLineNumbers={[321]}>
The name of the font.
</Prop>
<Prop name="weights" required type="FontWeight[]" sourceLineNumbers={[325]}>
The available font weights for the font.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>weights</strong></>}>
<Prop.List>
<Prop name="weight" required type="FontWeightName" sourceLineNumbers={[385]}>
The name of the font weight.
<Prop.Extras>
**Available values**:
* `"normal"`
* `"thin"`
* `"extralight"`
* `"light"`
* `"medium"`
* `"semibold"`
* `"bold"`
* `"ultrabold"`
* `"heavy"`
</Prop.Extras>
</Prop>
<Prop name="styles" required type="FontStyle[]" sourceLineNumbers={[389]}>
The font styles available for this specific font weight.
<Prop.Extras>
**Available values**:
* `"normal"`
* `"italic"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" type="string" sourceLineNumbers={[329]}>
The URL of an image that renders a preview of the font.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Open Color Selector
API reference for the openColorSelector method.
Opens a color selector.
Usage
Open a color selector
typescript
import { type Anchor, openColorSelector } from "@canva/asset";
const anchor: Anchor = {
width: 200,
height: 40,
top: 100,
left: 100
};
await openColorSelector(anchor, {
scopes: ["solid"],
onColorSelect: (event) => {
if (event.selection.type === "solid") {
const color = event.selection.hexString;
}
}
});Open a color selector with a pre-selected color
typescript
import { type Anchor, type SolidColor, openColorSelector } from "@canva/asset";
const anchor: Anchor = {
width: 200,
height: 40,
top: 100,
left: 100
};
const preselectedColor: SolidColor = {
type: "solid",
hexString: "#ff0000"
};
await openColorSelector(anchor, {
scopes: ["solid"],
selectedColor: preselectedColor,
onColorSelect: (event) => {
if (event.selection.type === "solid") {
const color = event.selection.hexString;
}
}
});Close a color selector programmatically
typescript
import { type Anchor, openColorSelector } from "@canva/asset";
const anchor: Anchor = {
width: 200,
height: 40,
top: 100,
left: 100
};
const close = await openColorSelector(anchor, {
scopes: ["solid"],
onColorSelect: (event) => {
if (event.selection.type === "solid") {
const color = event.selection.hexString;
}
}
});
// Later: Close the color selector
close();Parameters
<Prop.List> <Prop name="anchor" required type="Anchor" sourceLineNumbers={[727]}> A bounding box.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>anchor</strong></>}>
<Prop.List>
<Prop name="height" required type="number" sourceLineNumbers={[49]}>
The height of the bounding box, in pixels.
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[53]}>
The width of the bounding box, in pixels.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[57]}>
The top position of the bounding box, in pixels.
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[61]}>
The left position of the bounding box, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="options" required type="ColorSelectorOpts<Scope>" sourceLineNumbers={[727]}> Options for configuring a color selector.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="scopes" required type="Scope[]" sourceLineNumbers={[213]}>
The supported scopes, used to determine the appearance and behavior of the color selector.
The only valid value is `"solid"`.
</Prop>
<Prop name="onColorSelect" required type="function" sourceLineNumbers={[230]}>
A callback that runs when the user selects a color.
**Parameters**
<Prop.List>
<Prop name="event" required type="ColorSelectionEvent<Scope>" sourceLineNumbers={[230]}>
The color selection event.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>event</strong></>}>
<Prop.List>
<Prop name="selection" required type="object" sourceLineNumbers={[196]}>
The selected color.
The exact properties depends on the configured `scope`.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selection</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[831]}>
The type of color.
The only valid value is `"solid"`.
</Prop>
<Prop name="hexString" required type="string" sourceLineNumbers={[841]}>
The color as a hexadecimal code.
This is always a 6-digit code that's prefixed with a `#` symbol.
<Prop.Extras>
**Example**
```ts
"#ff0099"
```
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
<Prop name="selectedColor" type="object" sourceLineNumbers={[225]}>
The color to display as selected when the color selector is opened.
This is only required if there are multiple UI components for selecting colors.
For example, if the app renders multiple `Swatch` components.
If this value is `undefined`, the most recently selected color will be displayed as selected.
This property only affects **Document colors** and **Default colors**.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectedColor</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[831]}>
The type of color.
The only valid value is `"solid"`.
</Prop>
<Prop name="hexString" required type="string" sourceLineNumbers={[841]}>
The color as a hexadecimal code.
This is always a 6-digit code that's prefixed with a `#` symbol.
<Prop.Extras>
**Example**
```ts
"#ff0099"
```
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
A function that closes the currently open color selector.
Promise<() => void>
Request Font Selection
API reference for the requestFontSelection method.
Opens a font picker.
Usage
Open a font picker
typescript
import { requestFontSelection } from "@canva/asset";
const response = await requestFontSelection();Open a font picker with a preselected font
typescript
import { type FontRef, requestFontSelection } from "@canva/asset";
const placeholderFontRef = "PLACEHOLDER_FONT_REF" as FontRef;
const response = await requestFontSelection({
selectedFontRef: placeholderFontRef
});Handle font selection response
typescript
import { requestFontSelection } from "@canva/asset";
const response = await requestFontSelection();
if (response.type === "completed") {
const { ref, name, weights } = response.font;
} else {
// Handle selection cancelled if needed
}Parameters
<Prop.List> <Prop name="request" type="FontSelectionRequest" sourceLineNumbers={[821]}> Options for configuring a font picker.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="selectedFontRef" type="FontRef" sourceLineNumbers={[348]}>
The ref of a font to display as selected when the font picker is opened.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
The result of selecting a font from a font picker. This is a Promise that resolves with the following object:
<Tabs> <Tab name="Completed"> <Prop.List> <Prop name="type" required type="string" sourceLineNumbers={[359]}> The type of result.
The only valid value is `"completed"`.
</Prop>
<Prop name="font" required type="Font" sourceLineNumbers={[363]}>
The selected font.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>font</strong></>}>
<Prop.List>
<Prop name="ref" required type="FontRef" sourceLineNumbers={[317]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="name" required type="string" sourceLineNumbers={[321]}>
The name of the font.
</Prop>
<Prop name="weights" required type="FontWeight[]" sourceLineNumbers={[325]}>
The available font weights for the font.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>weights</strong></>}>
<Prop.List>
<Prop name="weight" required type="FontWeightName" sourceLineNumbers={[385]}>
The name of the font weight.
<Prop.Extras>
**Available values**:
* `"normal"`
* `"thin"`
* `"extralight"`
* `"light"`
* `"medium"`
* `"semibold"`
* `"bold"`
* `"ultrabold"`
* `"heavy"`
</Prop.Extras>
</Prop>
<Prop name="styles" required type="FontStyle[]" sourceLineNumbers={[389]}>
The font styles available for this specific font weight.
<Prop.Extras>
**Available values**:
* `"normal"`
* `"italic"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" type="string" sourceLineNumbers={[329]}>
The URL of an image that renders a preview of the font.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="Aborted"> <Prop.List> <Prop name="type" required type="string" sourceLineNumbers={[368]}> The type of result.
The only valid value is `"aborted"`.
</Prop>
</Prop.List>
</Tab> </Tabs>
Type Declarations
TypeScript type definitions for the @canva/asset package.
Tip: You can download the TypeScript types for the @canva/asset package here.
Asset API Changelog
The latest changes for the Canva Apps SDK @canva/asset package.
2.3.0 - 2025-12-22
Added
- Added optional
nameparameter toImageUploadOptionsandVideoUploadOptionsfor specifying a custom name for uploaded assets.
2.2.2 - 2025-12-18
Changed
- Increase video size limit from 100MB to 1GB and increase audio size limit from 50MB to 250MB for uploading assets
2.2.1 - 2025-07-08
Other
- Inline documentation improvements.
2.2.0 - 2025-04-01
Added
- Added support for
video/x-msvideoas an allowed MIME type
2.1.0 - 2024-12-15
Added
- Introduced a test harness to allow for unit testing of the package.
2.0.0 - 2024-09-19
Changed
- Breaking: See Apps SDK Migration Guide for full list of changes.
1.7.1 - 2024-08-07
Changed
- asset.upload now allows larger image uploads (25 MB -> 50 MB).
1.7.0 - 2024-07-23
Added
- Added asset.openColorSelector which was previously in beta.
- Added
selectedColorprop to asset.openColorSelector
1.6.0 - 2024-06-20
Added
- Added the ability to filter by
fontRefsin findFonts API.
1.5.0 - 2024-04-02
Added
- Added support for
TIFFinupload
1.4.0 - 2024-03-11
Added
- The property
idis now optional.
1.3.0 - 2024-02-25
Added
- Added getTemporaryUrl to get URL of an asset, which was previously available in preview mode.
- Added parentRef in
ImageUploadOptionsandVideoUploadOptionsto a reference to the original asset, which was previously available in preview mode.