Appearance
Apps SDK — Intents API
Prepare Content Publisher
API reference for the prepareContentPublisher method.
Prepares a Content Publisher Intent.
Usage
tsx
import { prepareContentPublisher } from "@canva/intents/content";
prepareContentPublisher({
getPublishConfiguration: async (params) => {
// Implement the logic to get the publish configuration
},
renderSettingsUi: (params) => {
// Implement the UI for settings view
},
renderPreviewUi: (params) => {
// Implement the UI for preview view
},
publishContent: async (params) => {
// Implement the logic to publish the content
},
});Parameters
<Prop.List> <Prop name="implementation" required type="ContentPublisherIntent" sourceLineNumbers={[1007]}> Main interface for implementing the ContentPublisher intent.
Implementing the ContentPublisher intent enables apps to publish contents to external platforms.
This allows users to configure publish settings, preview their designs, and share with others.
The publishing flow follows this process:
1. User initiates publish action
2. Your app provides publish configuration via `getPublishConfiguration`
3. User selects an output type
4. Your app renders settings UI via `renderSettingsUi`
5. Your app renders preview UI via `renderPreviewUi`
6. User reviews settings and preview
7. Your app publishes the content via `publishContent`
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>implementation</strong></>}>
<Prop.List>
<Prop name="getPublishConfiguration" required type="function" sourceLineNumbers={[189]}>
Provides the configuration for the publishing platform.
This action is called when the user initiates the publish flow and needs to
select an output type for the target platform.
Use this to define different publishing configurations for your platform,
such as social media posts, videos, or other output types.
<Prop.Extras>
**Example: Defining publish configuration for a social media platform**
```ts
import type { GetPublishConfigurationResponse } from '@canva/intents/content';
async function getPublishConfiguration(): Promise<GetPublishConfigurationResponse> {
return {
status: 'completed',
outputTypes: [
{
id: 'instagram_post',
displayName: 'Instagram Post',
mediaSlots: [
{
id: 'main_image',
displayName: 'Post Image',
fileCount: { min: 1, max: 10 },
accepts: {
image: { format: 'jpg', aspectRatio: { min: 0.8, max: 1.91 } }
}
}
]
}
]
};
}
```
</Prop.Extras>
**Returns**
A promise resolving to the publish configuration or an error. This is a `Promise` that resolves with the following object:
<Tabs>
<Tab name="GetPublishConfigurationCompleted">
Successful response from getting publish configuration.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[543]}>
The only valid value is `"completed"`.
</Prop>
<Prop name="outputTypes" required type="OutputTypeConfiguration[]" sourceLineNumbers={[550]}>
Array of available output types for your platform.
Define different output types for various content formats that
your platform supports (e.g., posts, stories, videos).
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>outputTypes</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[937]}>
Unique identifier for this output type.
Use descriptive IDs like `"instagram_post"` or `"youtube_video"`.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[944]}>
User-facing name for this output type.
This is displayed to users when selecting where to publish.
Examples: `"Instagram Post"`, `"YouTube Video"`, `"Twitter Post"`.
</Prop>
<Prop name="mediaSlots" required type="object[]" sourceLineNumbers={[953]}>
Array of media slots defining what content is needed.
Each slot represents a piece of media required for publishing,
such as a main image, thumbnail, or video.
The MediaSlot.selection field is omitted here because apps
do not provide selection data when defining output types.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>mediaSlots</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[732]}>
Unique identifier for this media slot within the output type.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[738]}>
User-facing name for this media slot.
Examples: `"Post Image"`, `"Video Thumbnail"`, `"Main Video"`.
</Prop>
<Prop name="accepts" required type="object" sourceLineNumbers={[761]}>
File type requirements for this slot.
Note the following behavior:
* Provide at least one of `image` or `video`
* If both are provided, files for this slot may be either images or videos; each file
must satisfy the corresponding requirement for its media type
* To restrict the slot to a single media type, provide only that requirement
* `fileCount` applies across all files accepted by the slot regardless of media type
* Document output types will show image previews (PNG thumbnail) in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>accepts</strong></>}>
<Prop.List>
<Prop name="image" type="ImageRequirement" sourceLineNumbers={[762]}>
Image file requirements for a media slot.
Specifies format, aspect ratio, and size constraints for images.
<Prop.Extras>
**Example: Image requirements for social media post**
```ts
const imageReq: ImageRequirement = {
format: 'jpg',
aspectRatio: { min: 0.8, max: 1.91 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>image</strong></>}>
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[65]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[656]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen (16:9)
* `{ min: 0.8, max: 1.91 }`: Instagram range
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[661]}>
<Prop.Extras>
**Available values**:
* `"jpg"`
* `"png"`
</Prop.Extras>
</Prop>
<Prop name="allowTransparentBackground" type="boolean" sourceLineNumbers={[678]}>
Controls transparent-background support for PNG exports.
* Only applies when `format` is `'png'`
* If omitted or `false`, Canva exports a standard opaque PNG
* If `true`, Canva shows a `Transparent background` toggle in the publish flow
* Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
<Prop.Extras>
**Default value**: `false`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="video" type="VideoRequirement" sourceLineNumbers={[763]}>
Video file requirements for a media slot.
Specifies format, aspect ratio, duration, and size constraints for videos.
<Prop.Extras>
**Example: Video requirements for YouTube**
```ts
const videoReq: VideoRequirement = {
format: 'mp4',
aspectRatio: { exact: 16/9 },
durationMs: { min: 1000, max: 600000 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>video</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[1706]}>
Supported video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[1714]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen
* `{ exact: 9/16 }`: Vertical/Story format
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="durationMs" type="ValueRange" sourceLineNumbers={[1722]}>
Duration constraint in milliseconds.
Examples:
* `{ max: 60000 }`: Maximum 60 seconds
* `{ min: 3000, max: 600000 }`: Between 3 seconds and 10 minutes
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="document" type="DocumentRequirement" sourceLineNumbers={[764]}>
Document file requirements for a media slot.
Note: Document output types use image previews (PNG thumbnails) in the preview UI.
The actual document file is only generated for the final output in OutputMedia.
<Prop.Extras>
**Example: Document requirements**
```ts
const documentReq: DocumentRequirement = {
format: 'pdf_standard',
size: 'a4',
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>document</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[418]}>
Supported document export format.
Currently supports PDF standard format.
The only valid value is `"pdf_standard"`.
</Prop>
<Prop name="size" required type="DocumentSize" sourceLineNumbers={[422]}>
The document size of the export file.
<Prop.Extras>
**Available values**:
* `"a4"`
* `"a3"`
* `"letter"`
* `"legal"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="email" type="EmailRequirement" sourceLineNumbers={[768]}>
Email output types will show a single html file (canva hosted assets) preview in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>email</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[508]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="fileCount" type="ValueRange" sourceLineNumbers={[748]}>
Number of files accepted in this slot.
Use this to specify single or multiple file requirements.
Examples:
* `{ exact: 1 }`: Exactly one file
* `{ min: 1, max: 10 }`: Between 1 and 10 files
* undefined: Any number of files
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="GetPublishConfigurationError">
GetPublishConfigurationError error indicating a custom error occurred.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[23]}>
The only valid value is `"app_error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[34]}>
(required) The raw error message, for logging purposes. It will not display in the UI.
To display custom error messages in the UI use `localizedMessageId`.
This should typically be the javascript error.message or a REST JSON error message
body passed without modification.
WARNING: Do not include personally identifiable information (PII) in this
message, such as names, emails, usernames, etc.
</Prop>
<Prop name="localizedMessageId" type="string" sourceLineNumbers={[41]}>
(optional) Message ID of the translated error message that will be
displayed to the user. The message ID should be present and uploaded in
your translation file. If omitted, Canva will display a generic error
message.
</Prop>
<Prop name="httpCode" type="number" sourceLineNumbers={[43]}>
HTTP status code, if applicable
</Prop>
<Prop name="appDefinedPayload" type="string" sourceLineNumbers={[48]}>
Used only by app developer. Canva does not use this value. Use this to pass
additional information like JSON to your settings frame.
</Prop>
<Prop name="errorCause" type="ErrorCause" sourceLineNumbers={[54]}>
(optional) Source of the error if it relates to a component on the Canva
UI. When present, the error may render near a relevant Canva component.
When omitted, the cause is considered unspecified or "generic".
<Prop.Extras>
**Available values**:
* `"invalid_selection"`
* `"invalid_format"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
<Prop name="renderSettingsUi" required type="function" sourceLineNumbers={[219]}>
Renders a user interface for configuring publish settings.
This action is called after the user selects an output type. Your UI should
allow users to configure platform-specific settings such as captions, tags,
privacy settings, or publishing destinations.
Use the `updatePublishSettings` callback to save user settings and validate them.
Settings are stored in the `publishRef` string (maximum 32KB).
<Prop.Extras>
**Example: Rendering a settings UI with publish configuration**
```ts
import { createRoot } from 'react-dom/client';
import type { RenderSettingsUiRequest } from '@canva/intents/content';
function renderSettingsUi(request: RenderSettingsUiRequest): void {
const SettingsUiApp = () => (
<AppUiProvider>
<SettingsUi request={request} />
</AppUiProvider>
);
createRoot().render(<SettingsUiApp />)
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="request" required type="RenderSettingsUiRequest" sourceLineNumbers={[219]}>
Configuration and callbacks for the publish settings UI.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="invocationContext" required type="RenderSettingsUiInvocationContext" sourceLineNumbers={[1415]}>
The initial settings and context provided when the settings UI is rendered.
Contains any previously saved publish settings and information about the current output type being configured.
Use this to restore the UI to its previous state or initialise it with appropriate defaults.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>invocationContext</strong></>}>
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[1279]}>
Initial settings and context provided when the settings UI is rendered.
The only valid value is `"publish"`.
</Prop>
<Prop name="publishRef" type="string" sourceLineNumbers={[1281]}>
Current publish reference to populate the UI, if any exist
</Prop>
<Prop name="outputType" type="OutputType" sourceLineNumbers={[1283]}>
Information about the current output type being configured
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>outputType</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[887]}>
Unique identifier for this output type.
Use descriptive IDs like `"instagram_post"` or `"youtube_video"`.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[894]}>
User-facing name for this output type.
This is displayed to users when selecting where to publish.
Examples: `"Instagram Post"`, `"YouTube Video"`, `"Twitter Post"`.
</Prop>
<Prop name="mediaSlots" required type="MediaSlot[]" sourceLineNumbers={[901]}>
Array of media slots defining what content is needed.
Each slot represents a piece of media required for publishing,
such as a main image, thumbnail, or video.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>mediaSlots</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[732]}>
Unique identifier for this media slot within the output type.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[738]}>
User-facing name for this media slot.
Examples: `"Post Image"`, `"Video Thumbnail"`, `"Main Video"`.
</Prop>
<Prop name="accepts" required type="object" sourceLineNumbers={[761]}>
File type requirements for this slot.
Note the following behavior:
* Provide at least one of `image` or `video`
* If both are provided, files for this slot may be either images or videos; each file
must satisfy the corresponding requirement for its media type
* To restrict the slot to a single media type, provide only that requirement
* `fileCount` applies across all files accepted by the slot regardless of media type
* Document output types will show image previews (PNG thumbnail) in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>accepts</strong></>}>
<Prop.List>
<Prop name="image" type="ImageRequirement" sourceLineNumbers={[762]}>
Image file requirements for a media slot.
Specifies format, aspect ratio, and size constraints for images.
<Prop.Extras>
**Example: Image requirements for social media post**
```ts
const imageReq: ImageRequirement = {
format: 'jpg',
aspectRatio: { min: 0.8, max: 1.91 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>image</strong></>}>
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[65]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[656]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen (16:9)
* `{ min: 0.8, max: 1.91 }`: Instagram range
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[661]}>
<Prop.Extras>
**Available values**:
* `"jpg"`
* `"png"`
</Prop.Extras>
</Prop>
<Prop name="allowTransparentBackground" type="boolean" sourceLineNumbers={[678]}>
Controls transparent-background support for PNG exports.
* Only applies when `format` is `'png'`
* If omitted or `false`, Canva exports a standard opaque PNG
* If `true`, Canva shows a `Transparent background` toggle in the publish flow
* Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
<Prop.Extras>
**Default value**: `false`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="video" type="VideoRequirement" sourceLineNumbers={[763]}>
Video file requirements for a media slot.
Specifies format, aspect ratio, duration, and size constraints for videos.
<Prop.Extras>
**Example: Video requirements for YouTube**
```ts
const videoReq: VideoRequirement = {
format: 'mp4',
aspectRatio: { exact: 16/9 },
durationMs: { min: 1000, max: 600000 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>video</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[1706]}>
Supported video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[1714]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen
* `{ exact: 9/16 }`: Vertical/Story format
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="durationMs" type="ValueRange" sourceLineNumbers={[1722]}>
Duration constraint in milliseconds.
Examples:
* `{ max: 60000 }`: Maximum 60 seconds
* `{ min: 3000, max: 600000 }`: Between 3 seconds and 10 minutes
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="document" type="DocumentRequirement" sourceLineNumbers={[764]}>
Document file requirements for a media slot.
Note: Document output types use image previews (PNG thumbnails) in the preview UI.
The actual document file is only generated for the final output in OutputMedia.
<Prop.Extras>
**Example: Document requirements**
```ts
const documentReq: DocumentRequirement = {
format: 'pdf_standard',
size: 'a4',
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>document</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[418]}>
Supported document export format.
Currently supports PDF standard format.
The only valid value is `"pdf_standard"`.
</Prop>
<Prop name="size" required type="DocumentSize" sourceLineNumbers={[422]}>
The document size of the export file.
<Prop.Extras>
**Available values**:
* `"a4"`
* `"a3"`
* `"letter"`
* `"legal"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="email" type="EmailRequirement" sourceLineNumbers={[768]}>
Email output types will show a single html file (canva hosted assets) preview in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>email</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[508]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="fileCount" type="ValueRange" sourceLineNumbers={[748]}>
Number of files accepted in this slot.
Use this to specify single or multiple file requirements.
Examples:
* `{ exact: 1 }`: Exactly one file
* `{ min: 1, max: 10 }`: Between 1 and 10 files
* undefined: Any number of files
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="selection" readonly type="MediaSelection[]" sourceLineNumbers={[779]}>
Current selection for this slot.
Canva populates this only when returning OutputType in Settings UI contexts
such as RenderSettingsUiInvocationContext and PublishSettingsSettingsUiContext.
Apps should not set this value when defining output types in
ContentPublisherIntent.getPublishConfiguration.
<Tabs>
<Tab name="ImageSelection">
Selection metadata for an image media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[686]}>
The only valid value is `"image"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoSelection">
Selection metadata for a video media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[1731]}>
The only valid value is `"video"`.
</Prop>
<Prop name="durationMs" required type="number" sourceLineNumbers={[1735]}>
Duration of the selected video in milliseconds.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentSelection">
Selection metadata for a document media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[430]}>
The only valid value is `"document"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailSelection">
Selection metadata for an email media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[516]}>
The only valid value is `"email"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="updatePublishSettings" required type="function" sourceLineNumbers={[1446]}>
Callback to save and validate the user's publish settings.
Call this function whenever the user modifies their settings to:
* Save the settings for later use in `publishContent`
* Validate that required fields are filled
* Enable or disable the publish button based on validity
Store all necessary publishing information in the `publishRef` string.
This will be provided to your `publishContent` method when the user publishes.
<Prop.Extras>
**Throws**
Will throw `CanvaError('bad_request')` if PublishSettings.publishRef exceeds 32KB.
**Example: Updating settings as user types**
```ts
// As user fills in form fields, update settings
function handleCaptionChange(caption: string) {
const settings = { caption, tags: currentTags };
const publishRef = JSON.stringify(settings);
updatePublishSettings({
publishRef,
validityState: caption ? 'valid' : 'invalid_missing_required_fields'
});
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="publishSettings" required type="PublishSettings" sourceLineNumbers={[1446]}>
Configuration for publish settings.
Contains the user's settings and their validation state. Use this to
control whether the publish button is enabled.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>publishSettings</strong></>}>
<Prop.List>
<Prop name="validityState" required type="PublishRefValidityState" sourceLineNumbers={[1252]}>
Validation state of the publish settings.
Controls whether the publish button is enabled:
* `"valid"`: Settings are complete and valid, publish button is enabled
* `"invalid_missing_required_fields"`: Required settings are missing, publish button is disabled
* `"invalid_authentication_required"`: User must authenticate before publishing can proceed
<Prop.Extras>
**Available values**:
* `"valid"`
* `"invalid_missing_required_fields"`
* `"invalid_authentication_required"`
</Prop.Extras>
</Prop>
<Prop name="publishRef" type="string" sourceLineNumbers={[1242]}>
Serialized platform-specific settings for publishing.
Store all information your app needs to publish the content in this string.
This might include:
* Captions or descriptions
* Tags or hashtags
* Privacy settings
* Publishing destination (account, page, etc.)
* Scheduling information
This reference will be provided to your `publishContent` method when publishing.
Maximum size: 32KB
<Prop.Extras>
**Example: Serializing settings**
```ts
const settings = {
caption: 'Check out my design!',
tags: ['design', 'creative'],
privacy: 'public'
};
const publishRef = JSON.stringify(settings);
```
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
A promise that resolves when the settings are successfully saved. This is a `Promise` that resolves with the following object:
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[1530]}>
The only valid value is `"completed"`.
</Prop>
</Prop.List>
</Prop>
<Prop name="registerOnContextChange" required type="function" sourceLineNumbers={[1476]}>
Registers a callback to be invoked when the settings UI context changes.
This callback is triggered when:
* the user changes the output type in the publish flow.
* an error occurs in the publish flow.
Use this to respond to Canva changes and update your settings UI accordingly.
<Prop.Extras>
**Example: Adapting UI for different output types**
```ts
registerOnContextChange({
onContextChange: (ctx) => {
if (ctx.reason === 'publish_settings') {
if (ctx.outputType.id === 'instagram_post') {
showHashtagField();
}
}
if (ctx.reason === 'publish_error') {
setError(ctx.error);
}
}
});
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="opts" required type="object" sourceLineNumbers={[1476]}>
The options for registering a callback.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="onContextChange" required type="OnContextChange" sourceLineNumbers={[1477]}>
**Parameters**
<Prop.List>
<Prop name="context" required type="SettingsUiContext" sourceLineNumbers={[809]}>
Context information for the publish settings UI.
<Tabs>
<Tab name="PublishSettingsSettingsUiContext">
Provides information about the current state of the settings UI to help
you adapt the interface based on the selected output type.
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[1261]}>
The only valid value is `"publish_settings"`.
</Prop>
<Prop name="outputType" required type="OutputType" sourceLineNumbers={[1268]}>
The currently selected output type.
Use this to customize your settings UI based on the requirements
of different output types.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>outputType</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[887]}>
Unique identifier for this output type.
Use descriptive IDs like `"instagram_post"` or `"youtube_video"`.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[894]}>
User-facing name for this output type.
This is displayed to users when selecting where to publish.
Examples: `"Instagram Post"`, `"YouTube Video"`, `"Twitter Post"`.
</Prop>
<Prop name="mediaSlots" required type="MediaSlot[]" sourceLineNumbers={[901]}>
Array of media slots defining what content is needed.
Each slot represents a piece of media required for publishing,
such as a main image, thumbnail, or video.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>mediaSlots</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[732]}>
Unique identifier for this media slot within the output type.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[738]}>
User-facing name for this media slot.
Examples: `"Post Image"`, `"Video Thumbnail"`, `"Main Video"`.
</Prop>
<Prop name="accepts" required type="object" sourceLineNumbers={[761]}>
File type requirements for this slot.
Note the following behavior:
* Provide at least one of `image` or `video`
* If both are provided, files for this slot may be either images or videos; each file
must satisfy the corresponding requirement for its media type
* To restrict the slot to a single media type, provide only that requirement
* `fileCount` applies across all files accepted by the slot regardless of media type
* Document output types will show image previews (PNG thumbnail) in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>accepts</strong></>}>
<Prop.List>
<Prop name="image" type="ImageRequirement" sourceLineNumbers={[762]}>
Image file requirements for a media slot.
Specifies format, aspect ratio, and size constraints for images.
<Prop.Extras>
**Example: Image requirements for social media post**
```ts
const imageReq: ImageRequirement = {
format: 'jpg',
aspectRatio: { min: 0.8, max: 1.91 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>image</strong></>}>
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[65]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[656]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen (16:9)
* `{ min: 0.8, max: 1.91 }`: Instagram range
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[661]}>
<Prop.Extras>
**Available values**:
* `"jpg"`
* `"png"`
</Prop.Extras>
</Prop>
<Prop name="allowTransparentBackground" type="boolean" sourceLineNumbers={[678]}>
Controls transparent-background support for PNG exports.
* Only applies when `format` is `'png'`
* If omitted or `false`, Canva exports a standard opaque PNG
* If `true`, Canva shows a `Transparent background` toggle in the publish flow
* Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
<Prop.Extras>
**Default value**: `false`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="video" type="VideoRequirement" sourceLineNumbers={[763]}>
Video file requirements for a media slot.
Specifies format, aspect ratio, duration, and size constraints for videos.
<Prop.Extras>
**Example: Video requirements for YouTube**
```ts
const videoReq: VideoRequirement = {
format: 'mp4',
aspectRatio: { exact: 16/9 },
durationMs: { min: 1000, max: 600000 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>video</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[1706]}>
Supported video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[1714]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen
* `{ exact: 9/16 }`: Vertical/Story format
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="durationMs" type="ValueRange" sourceLineNumbers={[1722]}>
Duration constraint in milliseconds.
Examples:
* `{ max: 60000 }`: Maximum 60 seconds
* `{ min: 3000, max: 600000 }`: Between 3 seconds and 10 minutes
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="document" type="DocumentRequirement" sourceLineNumbers={[764]}>
Document file requirements for a media slot.
Note: Document output types use image previews (PNG thumbnails) in the preview UI.
The actual document file is only generated for the final output in OutputMedia.
<Prop.Extras>
**Example: Document requirements**
```ts
const documentReq: DocumentRequirement = {
format: 'pdf_standard',
size: 'a4',
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>document</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[418]}>
Supported document export format.
Currently supports PDF standard format.
The only valid value is `"pdf_standard"`.
</Prop>
<Prop name="size" required type="DocumentSize" sourceLineNumbers={[422]}>
The document size of the export file.
<Prop.Extras>
**Available values**:
* `"a4"`
* `"a3"`
* `"letter"`
* `"legal"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="email" type="EmailRequirement" sourceLineNumbers={[768]}>
Email output types will show a single html file (canva hosted assets) preview in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>email</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[508]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="fileCount" type="ValueRange" sourceLineNumbers={[748]}>
Number of files accepted in this slot.
Use this to specify single or multiple file requirements.
Examples:
* `{ exact: 1 }`: Exactly one file
* `{ min: 1, max: 10 }`: Between 1 and 10 files
* undefined: Any number of files
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="selection" readonly type="MediaSelection[]" sourceLineNumbers={[779]}>
Current selection for this slot.
Canva populates this only when returning OutputType in Settings UI contexts
such as RenderSettingsUiInvocationContext and PublishSettingsSettingsUiContext.
Apps should not set this value when defining output types in
ContentPublisherIntent.getPublishConfiguration.
<Tabs>
<Tab name="ImageSelection">
Selection metadata for an image media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[686]}>
The only valid value is `"image"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoSelection">
Selection metadata for a video media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[1731]}>
The only valid value is `"video"`.
</Prop>
<Prop name="durationMs" required type="number" sourceLineNumbers={[1735]}>
Duration of the selected video in milliseconds.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentSelection">
Selection metadata for a document media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[430]}>
The only valid value is `"document"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailSelection">
Selection metadata for an email media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[516]}>
The only valid value is `"email"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="PublishErrorSettingsUiContext">
Provides information about an error that occurred in publishContent.
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[1168]}>
The only valid value is `"publish_error"`.
</Prop>
<Prop name="error" required type="PublishError" sourceLineNumbers={[1173]}>
The error that occurred. Undefined means no error occurred or the previous
error was cleared by Canva.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>error</strong></>}>
<Prop.List />
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="PublishErrorClearedSettingsUiContext">
Signals that the publish error was cleared.
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[1160]}>
The only valid value is `"publish_error_cleared"`.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
A disposer function that cleans up the registered callback.
() => `void`
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
<Prop name="renderPreviewUi" required type="function" sourceLineNumbers={[248]}>
Renders a user interface for previewing the content.
This action is called after the settings UI is rendered. Your UI should display
a preview of how the content will appear on the target platform.
Previews update dynamically as users modify their content or settings. For videos,
start with lightweight thumbnails and use `requestPreviewUpgrade` to load full
video previews on demand to optimize performance.
<Prop.Extras>
**Example: Rendering a preview UI with video optimization**
```ts
import { createRoot } from 'react-dom/client';
import type { RenderPreviewUiRequest } from '@canva/intents/content';
function renderPreviewUi(request: RenderPreviewUiRequest): void {
const PreviewUiApp = () => (
<AppUiProvider>
<PreviewUi request={request} />
</AppUiProvider>
);
createRoot().render(<PreviewUiApp />)
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="request" required type="RenderPreviewUiRequest" sourceLineNumbers={[248]}>
Configuration and callbacks for the preview UI.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="invocationContext" required type="RenderPreviewUiInvocationContext" sourceLineNumbers={[1331]}>
The initial preview data and context provided when the preview UI is rendered.
Contains the initial preview media, output type information, and any existing
publish settings needed to properly display the preview interface.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>invocationContext</strong></>}>
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[1190]}>
Initial preview data and context provided when the preview UI is rendered.
The only valid value is `"publish"`.
</Prop>
<Prop name="previewMedia" type="PreviewMedia[]" sourceLineNumbers={[1195]}>
Initial preview media to display
This will only be used for scheduling and not caching
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewMedia</strong></>}>
<Prop.List>
<Prop name="mediaSlotId" required type="string" sourceLineNumbers={[1035]}>
ID of the media slot this preview belongs to.
Matches a media slot ID from your output type definition.
</Prop>
<Prop name="previews" required type="Preview[]" sourceLineNumbers={[1041]}>
Array of preview items for this media slot.
May contain multiple previews if the media slot accepts multiple files.
<Tabs>
<Tab name="ImagePreview">
Image preview in various states.
<Tabs>
<Tab name="ImagePreviewLoading">
Image preview that is currently being generated.
Display a loading state until the preview transitions to `"ready"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[609]}>
Type of media in this preview.
The only valid value is `"image"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[610]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="ImagePreviewReady">
Image preview that is ready to display.
Contains the URL to the preview image.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[620]}>
Type of media in this preview.
The only valid value is `"image"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[621]}>
Current state of the preview.
The only valid value is `"ready"`.
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[625]}>
Image format of the preview.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[631]}>
URL to the preview image.
Use this URL to display the preview to users.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="ImagePreviewError">
Image preview that failed to generate.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[593]}>
Type of media in this preview.
The only valid value is `"image"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[594]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[599]}>
The error message to display to the user.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="VideoPreview">
Video preview in various states.
Videos transition through states: `"loading"` → `"thumbnail"` → `"upgrading"` → `"ready"`.
Start with thumbnails for better performance, then upgrade to full video using `requestPreviewUpgrade`.
<Tabs>
<Tab name="VideoPreviewLoading">
Video preview that is currently being generated.
Display a loading state until the preview transitions to `"thumbnail"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1593]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1594]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1598]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewThumbnail">
Video preview with lightweight thumbnail available.
This is the initial state for video previews. Show the thumbnail image
and call `requestPreviewUpgrade` when the user needs the full video.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1644]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1645]}>
Current state of the preview.
The only valid value is `"thumbnail"`.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[1649]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[1655]}>
URL to the thumbnail image.
Display this lightweight image until full video is needed.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1659]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewUpgrading">
Video preview that is being upgraded from thumbnail to full video.
Display the thumbnail with a loading indicator until the video is ready.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1669]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1670]}>
Current state of the preview.
The only valid value is `"upgrading"`.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[1674]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[1680]}>
URL to the thumbnail image.
Continue showing the thumbnail while the full video loads.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1684]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewReady">
Video preview with full video ready to play.
Contains URLs for both the video and thumbnail.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1608]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1609]}>
Current state of the preview.
The only valid value is `"ready"`.
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[1613]}>
Video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[1619]}>
URL to the full video.
Use this URL in a video player.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[1623]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[1629]}>
URL to the thumbnail image.
Can be used as a poster image for the video player.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1633]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewError">
Video preview that failed to generate.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1577]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1578]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[1583]}>
The error message to display to the user.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="DocumentPreview">
Document preview in various states.
Documents transition through states: `"loading"` → `"thumbnail"`.
Start with a lightweight thumbnail of the first page for quick preview rendering.
<Tabs>
<Tab name="DocumentPreviewLoading">
Document preview that is currently being generated.
Display a loading state until the preview transitions to `"thumbnail"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[371]}>
Type of media in this preview.
The only valid value is `"document"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[372]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentPreviewThumbnail">
Document preview with first page thumbnail available.
This is the initial state for document previews. Show the thumbnail image
of the first page along with the page count to give users a preview of
the document before publishing.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[384]}>
Type of media in this preview.
The only valid value is `"document"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[385]}>
Current state of the preview.
The only valid value is `"thumbnail"`.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[389]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[395]}>
URL to the first page thumbnail.
Display this lightweight image to preview the document content.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentPreviewError">
Document preview that failed to generate.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[356]}>
Type of media in this preview.
The only valid value is `"document"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[357]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[361]}>
The error message to display to the user.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="EmailPreview">
Email preview in various states.
Display a loading state until the preview transitions to `"ready"` or `"error"`.
<Tabs>
<Tab name="EmailPreviewLoading">
Email preview in a loading state.
Display a loading spinner until the preview transitions to `"ready"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[474]}>
Type of media in this preview.
The only valid value is `"email"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[475]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailPreviewReady">
Email preview in a ready state.
Display the email preview.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[485]}>
Type of media in this preview.
The only valid value is `"email"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[486]}>
Current state of the preview.
The only valid value is `"ready"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[490]}>
URL to the single html file that represents the email.
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailPreviewError">
Email preview in an error state.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[462]}>
Type of media in this preview.
The only valid value is `"email"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[463]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="outputType" type="OutputType" sourceLineNumbers={[1197]}>
Information about the current output type being previewed
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>outputType</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[887]}>
Unique identifier for this output type.
Use descriptive IDs like `"instagram_post"` or `"youtube_video"`.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[894]}>
User-facing name for this output type.
This is displayed to users when selecting where to publish.
Examples: `"Instagram Post"`, `"YouTube Video"`, `"Twitter Post"`.
</Prop>
<Prop name="mediaSlots" required type="MediaSlot[]" sourceLineNumbers={[901]}>
Array of media slots defining what content is needed.
Each slot represents a piece of media required for publishing,
such as a main image, thumbnail, or video.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>mediaSlots</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[732]}>
Unique identifier for this media slot within the output type.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[738]}>
User-facing name for this media slot.
Examples: `"Post Image"`, `"Video Thumbnail"`, `"Main Video"`.
</Prop>
<Prop name="accepts" required type="object" sourceLineNumbers={[761]}>
File type requirements for this slot.
Note the following behavior:
* Provide at least one of `image` or `video`
* If both are provided, files for this slot may be either images or videos; each file
must satisfy the corresponding requirement for its media type
* To restrict the slot to a single media type, provide only that requirement
* `fileCount` applies across all files accepted by the slot regardless of media type
* Document output types will show image previews (PNG thumbnail) in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>accepts</strong></>}>
<Prop.List>
<Prop name="image" type="ImageRequirement" sourceLineNumbers={[762]}>
Image file requirements for a media slot.
Specifies format, aspect ratio, and size constraints for images.
<Prop.Extras>
**Example: Image requirements for social media post**
```ts
const imageReq: ImageRequirement = {
format: 'jpg',
aspectRatio: { min: 0.8, max: 1.91 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>image</strong></>}>
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[65]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[656]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen (16:9)
* `{ min: 0.8, max: 1.91 }`: Instagram range
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[661]}>
<Prop.Extras>
**Available values**:
* `"jpg"`
* `"png"`
</Prop.Extras>
</Prop>
<Prop name="allowTransparentBackground" type="boolean" sourceLineNumbers={[678]}>
Controls transparent-background support for PNG exports.
* Only applies when `format` is `'png'`
* If omitted or `false`, Canva exports a standard opaque PNG
* If `true`, Canva shows a `Transparent background` toggle in the publish flow
* Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
<Prop.Extras>
**Default value**: `false`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="video" type="VideoRequirement" sourceLineNumbers={[763]}>
Video file requirements for a media slot.
Specifies format, aspect ratio, duration, and size constraints for videos.
<Prop.Extras>
**Example: Video requirements for YouTube**
```ts
const videoReq: VideoRequirement = {
format: 'mp4',
aspectRatio: { exact: 16/9 },
durationMs: { min: 1000, max: 600000 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>video</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[1706]}>
Supported video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[1714]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen
* `{ exact: 9/16 }`: Vertical/Story format
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="durationMs" type="ValueRange" sourceLineNumbers={[1722]}>
Duration constraint in milliseconds.
Examples:
* `{ max: 60000 }`: Maximum 60 seconds
* `{ min: 3000, max: 600000 }`: Between 3 seconds and 10 minutes
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="document" type="DocumentRequirement" sourceLineNumbers={[764]}>
Document file requirements for a media slot.
Note: Document output types use image previews (PNG thumbnails) in the preview UI.
The actual document file is only generated for the final output in OutputMedia.
<Prop.Extras>
**Example: Document requirements**
```ts
const documentReq: DocumentRequirement = {
format: 'pdf_standard',
size: 'a4',
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>document</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[418]}>
Supported document export format.
Currently supports PDF standard format.
The only valid value is `"pdf_standard"`.
</Prop>
<Prop name="size" required type="DocumentSize" sourceLineNumbers={[422]}>
The document size of the export file.
<Prop.Extras>
**Available values**:
* `"a4"`
* `"a3"`
* `"letter"`
* `"legal"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="email" type="EmailRequirement" sourceLineNumbers={[768]}>
Email output types will show a single html file (canva hosted assets) preview in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>email</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[508]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="fileCount" type="ValueRange" sourceLineNumbers={[748]}>
Number of files accepted in this slot.
Use this to specify single or multiple file requirements.
Examples:
* `{ exact: 1 }`: Exactly one file
* `{ min: 1, max: 10 }`: Between 1 and 10 files
* undefined: Any number of files
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="selection" readonly type="MediaSelection[]" sourceLineNumbers={[779]}>
Current selection for this slot.
Canva populates this only when returning OutputType in Settings UI contexts
such as RenderSettingsUiInvocationContext and PublishSettingsSettingsUiContext.
Apps should not set this value when defining output types in
ContentPublisherIntent.getPublishConfiguration.
<Tabs>
<Tab name="ImageSelection">
Selection metadata for an image media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[686]}>
The only valid value is `"image"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoSelection">
Selection metadata for a video media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[1731]}>
The only valid value is `"video"`.
</Prop>
<Prop name="durationMs" required type="number" sourceLineNumbers={[1735]}>
Duration of the selected video in milliseconds.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentSelection">
Selection metadata for a document media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[430]}>
The only valid value is `"document"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailSelection">
Selection metadata for an email media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[516]}>
The only valid value is `"email"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="publishRef" type="string" sourceLineNumbers={[1199]}>
Current publish reference, if available
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="requestPreviewUpgrade" required type="function" sourceLineNumbers={[1351]}>
Callback to upgrade video thumbnail previews to full video media.
Call this function when you need full video previews instead of lightweight thumbnails.
This helps optimize performance by deferring full video loading until needed.
Upgrades may complete asynchronously; listen to `registerOnPreviewChange` for updates
to receive the upgraded video previews.
<Prop.Extras>
**Example: Upgrading video previews on user interaction**
```ts
// When user clicks on a video thumbnail, upgrade to full video
if (preview.kind === 'video' && preview.status === 'thumbnail') {
requestPreviewUpgrade([preview.id]);
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="previewIds" required type="string[]" sourceLineNumbers={[1351]}>
Array of preview IDs to upgrade from thumbnail to full video
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
<Prop name="registerOnPreviewChange" required type="function" sourceLineNumbers={[1384]}>
Registers a callback to be invoked when preview data changes.
This callback is triggered when:
* The design content changes
* The output type changes
* Preview media is upgraded from thumbnail to full video
* Export settings are modified
Use this to update your preview UI in real-time as users modify their design.
<Prop.Extras>
**Example: Handling preview updates**
```ts
const disposer = registerOnPreviewChange(({ previewMedia, outputType, publishRef }) => {
// Update your preview UI with the new preview media
previewMedia.forEach((media) => {
media.previews.forEach((preview) => {
if (preview.status === 'ready') {
displayPreview(preview);
}
});
});
});
// Clean up when preview UI is unmounted
onUnmount(() => disposer());
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="callback" required type="function" sourceLineNumbers={[1384]}>
The callback invoked when preview data is updated
**Parameters**
<Prop.List>
<Prop name="opts" required type="object" sourceLineNumbers={[1384]}>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="previewMedia" required type="PreviewMedia[]" sourceLineNumbers={[1385]}>
Preview media for a specific media slot.
Contains preview URLs and metadata for images or videos in the design.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewMedia</strong></>}>
<Prop.List>
<Prop name="mediaSlotId" required type="string" sourceLineNumbers={[1035]}>
ID of the media slot this preview belongs to.
Matches a media slot ID from your output type definition.
</Prop>
<Prop name="previews" required type="Preview[]" sourceLineNumbers={[1041]}>
Array of preview items for this media slot.
May contain multiple previews if the media slot accepts multiple files.
<Tabs>
<Tab name="ImagePreview">
Image preview in various states.
<Tabs>
<Tab name="ImagePreviewLoading">
Image preview that is currently being generated.
Display a loading state until the preview transitions to `"ready"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[609]}>
Type of media in this preview.
The only valid value is `"image"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[610]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="ImagePreviewReady">
Image preview that is ready to display.
Contains the URL to the preview image.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[620]}>
Type of media in this preview.
The only valid value is `"image"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[621]}>
Current state of the preview.
The only valid value is `"ready"`.
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[625]}>
Image format of the preview.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[631]}>
URL to the preview image.
Use this URL to display the preview to users.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="ImagePreviewError">
Image preview that failed to generate.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[593]}>
Type of media in this preview.
The only valid value is `"image"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[594]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[599]}>
The error message to display to the user.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="VideoPreview">
Video preview in various states.
Videos transition through states: `"loading"` → `"thumbnail"` → `"upgrading"` → `"ready"`.
Start with thumbnails for better performance, then upgrade to full video using `requestPreviewUpgrade`.
<Tabs>
<Tab name="VideoPreviewLoading">
Video preview that is currently being generated.
Display a loading state until the preview transitions to `"thumbnail"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1593]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1594]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1598]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewThumbnail">
Video preview with lightweight thumbnail available.
This is the initial state for video previews. Show the thumbnail image
and call `requestPreviewUpgrade` when the user needs the full video.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1644]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1645]}>
Current state of the preview.
The only valid value is `"thumbnail"`.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[1649]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[1655]}>
URL to the thumbnail image.
Display this lightweight image until full video is needed.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1659]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewUpgrading">
Video preview that is being upgraded from thumbnail to full video.
Display the thumbnail with a loading indicator until the video is ready.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1669]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1670]}>
Current state of the preview.
The only valid value is `"upgrading"`.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[1674]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[1680]}>
URL to the thumbnail image.
Continue showing the thumbnail while the full video loads.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1684]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewReady">
Video preview with full video ready to play.
Contains URLs for both the video and thumbnail.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1608]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1609]}>
Current state of the preview.
The only valid value is `"ready"`.
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[1613]}>
Video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[1619]}>
URL to the full video.
Use this URL in a video player.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[1623]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[1629]}>
URL to the thumbnail image.
Can be used as a poster image for the video player.
</Prop>
<Prop name="durationMs" type="number" sourceLineNumbers={[1633]}>
Video duration in milliseconds.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoPreviewError">
Video preview that failed to generate.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[1577]}>
Type of media in this preview.
The only valid value is `"video"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[1578]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[1583]}>
The error message to display to the user.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="DocumentPreview">
Document preview in various states.
Documents transition through states: `"loading"` → `"thumbnail"`.
Start with a lightweight thumbnail of the first page for quick preview rendering.
<Tabs>
<Tab name="DocumentPreviewLoading">
Document preview that is currently being generated.
Display a loading state until the preview transitions to `"thumbnail"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[371]}>
Type of media in this preview.
The only valid value is `"document"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[372]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentPreviewThumbnail">
Document preview with first page thumbnail available.
This is the initial state for document previews. Show the thumbnail image
of the first page along with the page count to give users a preview of
the document before publishing.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[384]}>
Type of media in this preview.
The only valid value is `"document"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[385]}>
Current state of the preview.
The only valid value is `"thumbnail"`.
</Prop>
<Prop name="thumbnailFormat" required type="string" sourceLineNumbers={[389]}>
Format of the thumbnail image.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
</Prop.Extras>
</Prop>
<Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[395]}>
URL to the first page thumbnail.
Display this lightweight image to preview the document content.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentPreviewError">
Document preview that failed to generate.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[356]}>
Type of media in this preview.
The only valid value is `"document"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[357]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[361]}>
The error message to display to the user.
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1518]}>
Width of the preview in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1522]}>
Height of the preview in pixels.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="EmailPreview">
Email preview in various states.
Display a loading state until the preview transitions to `"ready"` or `"error"`.
<Tabs>
<Tab name="EmailPreviewLoading">
Email preview in a loading state.
Display a loading spinner until the preview transitions to `"ready"` or `"error"`.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[474]}>
Type of media in this preview.
The only valid value is `"email"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[475]}>
Current state of the preview.
The only valid value is `"loading"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailPreviewReady">
Email preview in a ready state.
Display the email preview.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[485]}>
Type of media in this preview.
The only valid value is `"email"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[486]}>
Current state of the preview.
The only valid value is `"ready"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[490]}>
URL to the single html file that represents the email.
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailPreviewError">
Email preview in an error state.
Display an error state to the user.
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[102]}>
Unique identifier for this preview.
Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
</Prop>
<Prop name="kind" required type="string" sourceLineNumbers={[462]}>
Type of media in this preview.
The only valid value is `"email"`.
</Prop>
<Prop name="status" required type="string" sourceLineNumbers={[463]}>
Current state of the preview.
The only valid value is `"error"`.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="outputType" required type="OutputType" sourceLineNumbers={[1387]}>
The output type that the preview data is for
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>outputType</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[887]}>
Unique identifier for this output type.
Use descriptive IDs like `"instagram_post"` or `"youtube_video"`.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[894]}>
User-facing name for this output type.
This is displayed to users when selecting where to publish.
Examples: `"Instagram Post"`, `"YouTube Video"`, `"Twitter Post"`.
</Prop>
<Prop name="mediaSlots" required type="MediaSlot[]" sourceLineNumbers={[901]}>
Array of media slots defining what content is needed.
Each slot represents a piece of media required for publishing,
such as a main image, thumbnail, or video.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>mediaSlots</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[732]}>
Unique identifier for this media slot within the output type.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[738]}>
User-facing name for this media slot.
Examples: `"Post Image"`, `"Video Thumbnail"`, `"Main Video"`.
</Prop>
<Prop name="accepts" required type="object" sourceLineNumbers={[761]}>
File type requirements for this slot.
Note the following behavior:
* Provide at least one of `image` or `video`
* If both are provided, files for this slot may be either images or videos; each file
must satisfy the corresponding requirement for its media type
* To restrict the slot to a single media type, provide only that requirement
* `fileCount` applies across all files accepted by the slot regardless of media type
* Document output types will show image previews (PNG thumbnail) in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>accepts</strong></>}>
<Prop.List>
<Prop name="image" type="ImageRequirement" sourceLineNumbers={[762]}>
Image file requirements for a media slot.
Specifies format, aspect ratio, and size constraints for images.
<Prop.Extras>
**Example: Image requirements for social media post**
```ts
const imageReq: ImageRequirement = {
format: 'jpg',
aspectRatio: { min: 0.8, max: 1.91 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>image</strong></>}>
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[65]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[656]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen (16:9)
* `{ min: 0.8, max: 1.91 }`: Instagram range
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[661]}>
<Prop.Extras>
**Available values**:
* `"jpg"`
* `"png"`
</Prop.Extras>
</Prop>
<Prop name="allowTransparentBackground" type="boolean" sourceLineNumbers={[678]}>
Controls transparent-background support for PNG exports.
* Only applies when `format` is `'png'`
* If omitted or `false`, Canva exports a standard opaque PNG
* If `true`, Canva shows a `Transparent background` toggle in the publish flow
* Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
<Prop.Extras>
**Default value**: `false`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="video" type="VideoRequirement" sourceLineNumbers={[763]}>
Video file requirements for a media slot.
Specifies format, aspect ratio, duration, and size constraints for videos.
<Prop.Extras>
**Example: Video requirements for YouTube**
```ts
const videoReq: VideoRequirement = {
format: 'mp4',
aspectRatio: { exact: 16/9 },
durationMs: { min: 1000, max: 600000 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>video</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[1706]}>
Supported video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[1714]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen
* `{ exact: 9/16 }`: Vertical/Story format
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="durationMs" type="ValueRange" sourceLineNumbers={[1722]}>
Duration constraint in milliseconds.
Examples:
* `{ max: 60000 }`: Maximum 60 seconds
* `{ min: 3000, max: 600000 }`: Between 3 seconds and 10 minutes
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="document" type="DocumentRequirement" sourceLineNumbers={[764]}>
Document file requirements for a media slot.
Note: Document output types use image previews (PNG thumbnails) in the preview UI.
The actual document file is only generated for the final output in OutputMedia.
<Prop.Extras>
**Example: Document requirements**
```ts
const documentReq: DocumentRequirement = {
format: 'pdf_standard',
size: 'a4',
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>document</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[418]}>
Supported document export format.
Currently supports PDF standard format.
The only valid value is `"pdf_standard"`.
</Prop>
<Prop name="size" required type="DocumentSize" sourceLineNumbers={[422]}>
The document size of the export file.
<Prop.Extras>
**Available values**:
* `"a4"`
* `"a3"`
* `"letter"`
* `"legal"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="email" type="EmailRequirement" sourceLineNumbers={[768]}>
Email output types will show a single html file (canva hosted assets) preview in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>email</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[508]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="fileCount" type="ValueRange" sourceLineNumbers={[748]}>
Number of files accepted in this slot.
Use this to specify single or multiple file requirements.
Examples:
* `{ exact: 1 }`: Exactly one file
* `{ min: 1, max: 10 }`: Between 1 and 10 files
* undefined: Any number of files
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="selection" readonly type="MediaSelection[]" sourceLineNumbers={[779]}>
Current selection for this slot.
Canva populates this only when returning OutputType in Settings UI contexts
such as RenderSettingsUiInvocationContext and PublishSettingsSettingsUiContext.
Apps should not set this value when defining output types in
ContentPublisherIntent.getPublishConfiguration.
<Tabs>
<Tab name="ImageSelection">
Selection metadata for an image media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[686]}>
The only valid value is `"image"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoSelection">
Selection metadata for a video media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[1731]}>
The only valid value is `"video"`.
</Prop>
<Prop name="durationMs" required type="number" sourceLineNumbers={[1735]}>
Duration of the selected video in milliseconds.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentSelection">
Selection metadata for a document media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[430]}>
The only valid value is `"document"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="EmailSelection">
Selection metadata for an email media item.
<Prop.List>
<Prop name="kind" required type="string" sourceLineNumbers={[516]}>
The only valid value is `"email"`.
</Prop>
<Prop name="selectionMetadata" type="SelectionDesignMetadata[]" sourceLineNumbers={[124]}>
Metadata about the source content represented by this selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>selectionMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1487]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[1491]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[1495]}>
The user given title of the design
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="publishRef" type="string" sourceLineNumbers={[1389]}>
The current publish settings reference, if available
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
</Prop.List>
**Returns**
A disposer function that cleans up the registered callback.
() => `void`
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
<Prop name="publishContent" required type="function" sourceLineNumbers={[300]}>
Publishes the content to the external platform.
This action is called when the user confirms the publish action after reviewing
settings and preview. Your implementation should send the exported files
to your platform's API.
The `outputMedia` contains production-ready files that match the requirements
specified in your output types. The `publishRef` contains the user's settings
from the settings UI.
<Prop.Extras>
**Example: Publishing content to an external platform**
```ts
import type { PublishContentRequest, PublishContentResponse } from '@canva/intents/content';
async function publishContent(request: PublishContentRequest): Promise<PublishContentResponse> {
const { publishRef, outputType, outputMedia } = request;
try {
// Parse settings from publishRef
const settings = publishRef ? JSON.parse(publishRef) : {};
// Upload files to your platform
const uploadedFiles = await Promise.all(
outputMedia.flatMap(media =>
media.files.map(file => uploadFile(file.url))
)
);
// Create post on your platform
const result = await createPost({
files: uploadedFiles,
caption: settings.caption
});
return {
status: 'completed',
externalId: result.id,
externalUrl: result.url
};
} catch (error) {
return {
status: 'remote_request_failed'
};
}
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="request" required type="PublishContentRequest" sourceLineNumbers={[300]}>
Parameters for the publish operation.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="outputType" required type="OutputTypeConfiguration" sourceLineNumbers={[1132]}>
The output type selected by the user for this publish operation.
This matches one of the output types you provided in `getPublishConfiguration`.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>outputType</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[937]}>
Unique identifier for this output type.
Use descriptive IDs like `"instagram_post"` or `"youtube_video"`.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[944]}>
User-facing name for this output type.
This is displayed to users when selecting where to publish.
Examples: `"Instagram Post"`, `"YouTube Video"`, `"Twitter Post"`.
</Prop>
<Prop name="mediaSlots" required type="object[]" sourceLineNumbers={[953]}>
Array of media slots defining what content is needed.
Each slot represents a piece of media required for publishing,
such as a main image, thumbnail, or video.
The MediaSlot.selection field is omitted here because apps
do not provide selection data when defining output types.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>mediaSlots</strong></>}>
<Prop.List>
<Prop name="id" required type="string" sourceLineNumbers={[732]}>
Unique identifier for this media slot within the output type.
</Prop>
<Prop name="displayName" required type="string" sourceLineNumbers={[738]}>
User-facing name for this media slot.
Examples: `"Post Image"`, `"Video Thumbnail"`, `"Main Video"`.
</Prop>
<Prop name="accepts" required type="object" sourceLineNumbers={[761]}>
File type requirements for this slot.
Note the following behavior:
* Provide at least one of `image` or `video`
* If both are provided, files for this slot may be either images or videos; each file
must satisfy the corresponding requirement for its media type
* To restrict the slot to a single media type, provide only that requirement
* `fileCount` applies across all files accepted by the slot regardless of media type
* Document output types will show image previews (PNG thumbnail) in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>accepts</strong></>}>
<Prop.List>
<Prop name="image" type="ImageRequirement" sourceLineNumbers={[762]}>
Image file requirements for a media slot.
Specifies format, aspect ratio, and size constraints for images.
<Prop.Extras>
**Example: Image requirements for social media post**
```ts
const imageReq: ImageRequirement = {
format: 'jpg',
aspectRatio: { min: 0.8, max: 1.91 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>image</strong></>}>
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[65]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[656]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen (16:9)
* `{ min: 0.8, max: 1.91 }`: Instagram range
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="format" required type="string" sourceLineNumbers={[661]}>
<Prop.Extras>
**Available values**:
* `"jpg"`
* `"png"`
</Prop.Extras>
</Prop>
<Prop name="allowTransparentBackground" type="boolean" sourceLineNumbers={[678]}>
Controls transparent-background support for PNG exports.
* Only applies when `format` is `'png'`
* If omitted or `false`, Canva exports a standard opaque PNG
* If `true`, Canva shows a `Transparent background` toggle in the publish flow
* Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
<Prop.Extras>
**Default value**: `false`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="video" type="VideoRequirement" sourceLineNumbers={[763]}>
Video file requirements for a media slot.
Specifies format, aspect ratio, duration, and size constraints for videos.
<Prop.Extras>
**Example: Video requirements for YouTube**
```ts
const videoReq: VideoRequirement = {
format: 'mp4',
aspectRatio: { exact: 16/9 },
durationMs: { min: 1000, max: 600000 },
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>video</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[1706]}>
Supported video format.
The only valid value is `"mp4"`.
</Prop>
<Prop name="aspectRatio" type="ValueRange" sourceLineNumbers={[1714]}>
Aspect ratio constraint (width / height).
Examples:
* `{ exact: 16/9 }`: Widescreen
* `{ exact: 9/16 }`: Vertical/Story format
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
<Prop name="durationMs" type="ValueRange" sourceLineNumbers={[1722]}>
Duration constraint in milliseconds.
Examples:
* `{ max: 60000 }`: Maximum 60 seconds
* `{ min: 3000, max: 600000 }`: Between 3 seconds and 10 minutes
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="document" type="DocumentRequirement" sourceLineNumbers={[764]}>
Document file requirements for a media slot.
Note: Document output types use image previews (PNG thumbnails) in the preview UI.
The actual document file is only generated for the final output in OutputMedia.
<Prop.Extras>
**Example: Document requirements**
```ts
const documentReq: DocumentRequirement = {
format: 'pdf_standard',
size: 'a4',
};
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>document</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[418]}>
Supported document export format.
Currently supports PDF standard format.
The only valid value is `"pdf_standard"`.
</Prop>
<Prop name="size" required type="DocumentSize" sourceLineNumbers={[422]}>
The document size of the export file.
<Prop.Extras>
**Available values**:
* `"a4"`
* `"a3"`
* `"letter"`
* `"legal"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="email" type="EmailRequirement" sourceLineNumbers={[768]}>
Email output types will show a single html file (canva hosted assets) preview in preview UI
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>email</strong></>}>
<Prop.List>
<Prop name="format" required type="string" sourceLineNumbers={[508]}>
File format for this requirement.
<Prop.Extras>
**Available values**:
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="fileCount" type="ValueRange" sourceLineNumbers={[748]}>
Number of files accepted in this slot.
Use this to specify single or multiple file requirements.
Examples:
* `{ exact: 1 }`: Exactly one file
* `{ min: 1, max: 10 }`: Between 1 and 10 files
* undefined: Any number of files
<Tabs>
<Tab name="ExactValueRange">
Exact value range constraint.
<Prop.Extras>
**Example: Exact value range**
```ts
const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinValueRange">
Minimum value range constraint.
<Prop.Extras>
**Example: Minimum value range**
```ts
const minValue: ValueRange = { min: 3 }; // At least 3
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MaxValueRange">
Maximum value range constraint.
<Prop.Extras>
**Example: Maximum value range**
```ts
const maxValue: ValueRange = { max: 10 }; // At most 10
```
</Prop.Extras>
<Prop.List />
</Tab>
<Tab name="MinMaxValueRange">
Minimum and maximum value range constraint.
Ranges are inclusive `(min ≤ value ≤ max)`.
<Prop.Extras>
**Example: Minimum and maximum value range**
```ts
const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
```
</Prop.Extras>
<Prop.List />
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="outputMedia" required type="OutputMedia[]" sourceLineNumbers={[1139]}>
Production-ready exported files matching the requirements from your output type.
These files are ready to upload to your platform and match the format, size,
and aspect ratio requirements specified in your media slots.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>outputMedia</strong></>}>
<Prop.List>
<Prop name="mediaSlotId" required type="string" sourceLineNumbers={[829]}>
ID of the media slot these files belong to.
Matches a media slot ID from your output type definition.
</Prop>
<Prop name="files" required type="OutputFile[]" sourceLineNumbers={[835]}>
Array of exported files for this media slot.
Files match the requirements specified in your media slot configuration.
<Tabs>
<Tab name="ImageOutputFile">
Exported image file ready for publishing.
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[77]}>
File format.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[83]}>
URL to download the exported file.
Your app should download from this URL and upload to your platform.
</Prop>
<Prop name="contentMetadata" required type="DesignContentMetadata" sourceLineNumbers={[87]}>
Metadata about the source content used to create this exported file.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>contentMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[309]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[313]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[317]}>
The user given title of the design
</Prop>
<Prop name="pages" required type="OutputPageMetadata[]" sourceLineNumbers={[321]}>
The pages that make up the exported metadata
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>pages</strong></>}>
<Prop.List>
<Prop name="pageId" required type="string | undefined" sourceLineNumbers={[846]}>
The unique identifier for the page.
</Prop>
<Prop name="pageNumber" required type="number" sourceLineNumbers={[850]}>
The position of the page within the design, starting from 1 for the first page.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[573]}>
Width of the image in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[577]}>
Height of the image in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="VideoOutputFile">
Exported video file ready for publishing.
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[77]}>
File format.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[83]}>
URL to download the exported file.
Your app should download from this URL and upload to your platform.
</Prop>
<Prop name="contentMetadata" required type="DesignContentMetadata" sourceLineNumbers={[87]}>
Metadata about the source content used to create this exported file.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>contentMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[309]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[313]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[317]}>
The user given title of the design
</Prop>
<Prop name="pages" required type="OutputPageMetadata[]" sourceLineNumbers={[321]}>
The pages that make up the exported metadata
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>pages</strong></>}>
<Prop.List>
<Prop name="pageId" required type="string | undefined" sourceLineNumbers={[846]}>
The unique identifier for the page.
</Prop>
<Prop name="pageNumber" required type="number" sourceLineNumbers={[850]}>
The position of the page within the design, starting from 1 for the first page.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="widthPx" required type="number" sourceLineNumbers={[1554]}>
Width of the video in pixels.
</Prop>
<Prop name="heightPx" required type="number" sourceLineNumbers={[1558]}>
Height of the video in pixels.
</Prop>
</Prop.List>
</Tab>
<Tab name="DocumentOutputFile">
Exported PDF file ready for publishing.
Contains the final PDF document that should be uploaded to your platform.
The document format is `pdf_standard` and the file is ready to use.
<Prop.List>
<Prop name="format" required type="PublishFileFormat" sourceLineNumbers={[77]}>
File format.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"mp4"`
* `"pdf_standard"`
* `"html_bundle"`
* `"html_standalone"`
</Prop.Extras>
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[83]}>
URL to download the exported file.
Your app should download from this URL and upload to your platform.
</Prop>
<Prop name="contentMetadata" required type="DesignContentMetadata" sourceLineNumbers={[87]}>
Metadata about the source content used to create this exported file.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>contentMetadata</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[309]}>
The only valid value is `"design"`.
</Prop>
<Prop name="designToken" required type="string" sourceLineNumbers={[313]}>
A signed JWT token containing the design id
</Prop>
<Prop name="title" required type="string | undefined" sourceLineNumbers={[317]}>
The user given title of the design
</Prop>
<Prop name="pages" required type="OutputPageMetadata[]" sourceLineNumbers={[321]}>
The pages that make up the exported metadata
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>pages</strong></>}>
<Prop.List>
<Prop name="pageId" required type="string | undefined" sourceLineNumbers={[846]}>
The unique identifier for the page.
</Prop>
<Prop name="pageNumber" required type="number" sourceLineNumbers={[850]}>
The position of the page within the design, starting from 1 for the first page.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="publishRef" type="string" sourceLineNumbers={[1126]}>
Platform-specific settings reference containing user configurations.
This is the same reference you saved via `updatePublishSettings` in the settings UI.
Parse this string to retrieve the user's publish settings (e.g., captions, tags, privacy).
Maximum size: 32KB
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
A promise resolving to either a successful result with the published content details or an error. This is a `Promise` that resolves with the following object:
<Tabs>
<Tab name="PublishContentCompleted">
Successful response from publishing a content.
<Prop.Extras>
**Examples**
**Basic successful publish**
```ts
return {
status: 'completed',
externalId: 'post_12345',
externalUrl: 'https://example.com/posts/12345'
};
```
**Successful publish with redirect**
```ts
return {
status: 'completed',
externalId: 'video_67890',
externalUrl: 'https://example.com/videos/67890',
postPublishAction: {
type: 'redirect',
url: 'https://example.com/videos/67890/edit'
}
};
```
</Prop.Extras>
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[1077]}>
The only valid value is `"completed"`.
</Prop>
<Prop name="externalId" type="string" sourceLineNumbers={[1085]}>
Unique identifier returned from your external platform. You can use this for:
* Tracking published content
* Fetching insights data for the published content
* Linking back to the content in future operations
</Prop>
<Prop name="externalUrl" type="string" sourceLineNumbers={[1092]}>
Direct URL to the published content on your platform.
Users can visit this URL to view their published content.
This may be displayed to users or used for sharing.
</Prop>
<Prop name="postPublishAction" type="PostPublishAction" sourceLineNumbers={[1098]}>
Optional action to perform after publishing completes.
Currently supports redirecting users to a specific URL after publishing.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>postPublishAction</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[975]}>
The only valid value is `"redirect"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[979]}>
The URL to redirect the user to after publishing.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="PublishContentError">
Error response from publishing a content.
Return the appropriate error type based on the failure:
* `"remote_request_failed"`: Network or API errors with your platform
* `"app_error"`: Custom application errors with optional message
<Tabs>
<Tab name="RemoteRequestFailedError">
PublishContentError indicating failure of the remote request to the external platform.
Return this error for:
* Network connectivity issues
* API endpoint failures
* HTTP errors from your platform
* Timeout errors
<Prop.Extras>
**Example: Handling network errors**
```ts
try {
await uploadToExternalPlatform(file);
} catch (error) {
return { status: 'remote_request_failed' };
}
```
</Prop.Extras>
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[1307]}>
The only valid value is `"remote_request_failed"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="AppError">
PublishContentError indicating a custom error occurred in your app's implementation.
Return this for application-specific errors such as:
* Validation failures
* Authentication errors
* Rate limiting
* Platform-specific restrictions
<Prop.Extras>
**Example: Returning custom error with message**
```ts
if (userQuotaExceeded) {
return {
status: 'app_error',
message: 'You have reached your monthly publish limit. Please upgrade your plan.'
};
}
```
</Prop.Extras>
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[23]}>
The only valid value is `"app_error"`.
</Prop>
<Prop name="message" required type="string" sourceLineNumbers={[34]}>
(required) The raw error message, for logging purposes. It will not display in the UI.
To display custom error messages in the UI use `localizedMessageId`.
This should typically be the javascript error.message or a REST JSON error message
body passed without modification.
WARNING: Do not include personally identifiable information (PII) in this
message, such as names, emails, usernames, etc.
</Prop>
<Prop name="localizedMessageId" type="string" sourceLineNumbers={[41]}>
(optional) Message ID of the translated error message that will be
displayed to the user. The message ID should be present and uploaded in
your translation file. If omitted, Canva will display a generic error
message.
</Prop>
<Prop name="httpCode" type="number" sourceLineNumbers={[43]}>
HTTP status code, if applicable
</Prop>
<Prop name="appDefinedPayload" type="string" sourceLineNumbers={[48]}>
Used only by app developer. Canva does not use this value. Use this to pass
additional information like JSON to your settings frame.
</Prop>
<Prop name="errorCause" type="ErrorCause" sourceLineNumbers={[54]}>
(optional) Source of the error if it relates to a component on the Canva
UI. When present, the error may render near a relevant Canva component.
When omitted, the cause is considered unspecified or "generic".
<Prop.Extras>
**Available values**:
* `"invalid_selection"`
* `"invalid_format"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
void
Prepare Data Connector
API reference for the intents prepareDataConnector method.
Prepares a DataConnector Intent.
Usage
tsx
import { prepareDataConnector } from "@canva/intents/data";
prepareDataConnector({
getDataTable: async (params) => {
// Implement the logic to fetch the data table
},
renderSelectionUi: (params) => {
// Implement the UI for the data table selection
},
});Parameters
<Prop.List> <Prop name="implementation" required type="DataConnectorIntent" sourceLineNumbers={[972]}> Main interface for implementing the Data Connector intent.
Implementing the Data Connector intent enables apps to import external data into Canva.
This allows users to select, preview, and refresh data from external sources.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>implementation</strong></>}>
<Prop.List>
<Prop name="getDataTable" required type="function" sourceLineNumbers={[194]}>
Gets structured data from an external source.
This action is called in two scenarios:
* During data selection to preview data before import (when RenderSelectionUiRequest.updateDataRef is called).
* When refreshing previously imported data (when the user requests an update).
<Prop.Extras>
**Example: Getting data from an external source**
```ts
import type { GetDataTableRequest, GetDataTableResponse } from '@canva/intents/data';
async function getDataTable(request: GetDataTableRequest): Promise<GetDataTableResponse> {
const { dataSourceRef, limit, signal } = request;
// Check if the operation has been aborted.
if (signal.aborted) {
return { status: 'app_error', message: 'The data fetch operation was cancelled.' };
}
// ... data fetching logic using dataSourceRef, limit, and signal ...
// Placeholder for a successful result.
return {
status: 'completed',
dataTable: { rows: [{ cells: [{ type: 'string', value: 'Fetched data' }] }] }
};
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="request" required type="GetDataTableRequest" sourceLineNumbers={[194]}>
Parameters for the data fetching operation.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="dataSourceRef" required type="DataSourceRef" sourceLineNumbers={[544]}>
Reference to the data source to fetch.
This contains the information needed to identify and retrieve the specific data
that was previously selected by the user.
Use this to query your external data service.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
<Prop.List>
<Prop name="source" required type="string" sourceLineNumbers={[282]}>
Information needed to identify and retrieve data from your source.
This string should contain all the information your app needs to
fetch the exact data selection later. Typically, this is a serialized
object with query parameters, identifiers, or filters.
You are responsible for encoding and decoding this value appropriately.
Maximum size: 5KB
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[291]}>
A human-readable description of the data reference.
This title may be displayed to users in the Canva interface to help
them identify the data source.
Maximum length: 255 characters
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="limit" required type="DataTableLimit" sourceLineNumbers={[555]}>
Maximum row and column limits for the imported data.
Your app must ensure the returned data does not exceed these limits.
If the requested data would exceed these limits, either:
* Truncate the data to fit within limits, or
* Return a 'data\_table\_limit\_exceeded' error
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>limit</strong></>}>
<Prop.List>
<Prop name="row" required type="number" sourceLineNumbers={[381]}>
The maximum number of rows allowed.
Your app should ensure data does not exceed this limit.
</Prop>
<Prop name="column" required type="number" sourceLineNumbers={[387]}>
The maximum number of columns allowed.
Your app should ensure data does not exceed this limit.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="signal" required type="AbortSignal" sourceLineNumbers={[561]}>
Standard DOM AbortSignal for cancellation support.
Your app should monitor this signal and abort any ongoing operations if it becomes aborted.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
A promise resolving to either a successful result with data or an error. This is a `Promise` that resolves with the following object:
<Tabs>
<Tab name="GetDataTableCompleted">
Successful result from `getDataTable` action.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[514]}>
Indicates the operation completed successfully
The only valid value is `"completed"`.
</Prop>
<Prop name="dataTable" required type="DataTable" sourceLineNumbers={[518]}>
The fetched data formatted as a data table.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataTable</strong></>}>
<Prop.List>
<Prop name="rows" required type="DataTableRow[]" sourceLineNumbers={[345]}>
The data rows containing the actual values.
Each row contains an array of cells with typed data values.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>rows</strong></>}>
<Prop.List>
<Prop name="cells" required type="DataTableCell<DataType>[]" sourceLineNumbers={[439]}>
Array of cells containing the data values.
Each cell must have a type that matches the corresponding column definition (if provided).
<Tabs>
<Tab name="date">
Cell containing a date value.
<Prop.Extras>
**Example: Creating a date cell**
```ts
import type { DateDataTableCell } from '@canva/intents/data';
const todayCell: DateDataTableCell = {
type: 'date',
value: Math.floor(Date.now() / 1000) // Unix timestamp in seconds
};
const emptyDateCell: DateDataTableCell = {
type: 'date',
value: undefined
};
```
</Prop.Extras>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[482]}>
Indicates this cell contains a date value.
The only valid value is `"date"`.
</Prop>
<Prop name="value" required type="number | undefined" sourceLineNumbers={[488]}>
Unix timestamp in seconds representing the date.
Use `undefined` for an empty cell.
</Prop>
</Prop.List>
</Tab>
<Tab name="string">
Cell containing a text value.
<Prop.Extras>
**Example: Creating a string cell**
```ts
import type { StringDataTableCell } from '@canva/intents/data';
const nameCell: StringDataTableCell = {
type: 'string',
value: 'John Doe'
};
const emptyStringCell: StringDataTableCell = {
type: 'string',
value: undefined
};
```
</Prop.Extras>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1058]}>
Indicates this cell contains a string value.
The only valid value is `"string"`.
</Prop>
<Prop name="value" required type="string | undefined" sourceLineNumbers={[1066]}>
Text content of the cell.
Maximum length: 10,000 characters
Use `undefined` for an empty cell.
</Prop>
</Prop.List>
</Tab>
<Tab name="number">
Cell containing a numeric value.
<Prop.Extras>
**Example: Creating a number cell**
```ts
import type { NumberCellMetadata, NumberDataTableCell } from '@canva/intents/data';
const priceCell: NumberDataTableCell = {
type: 'number',
value: 29.99,
metadata: { formatting: '[$$]#,##0.00' }
};
const quantityCell: NumberDataTableCell = {
type: 'number',
value: 150
};
const emptyNumberCell: NumberDataTableCell = {
type: 'number',
value: undefined
};
```
</Prop.Extras>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[878]}>
Indicates this cell contains a number value.
The only valid value is `"number"`.
</Prop>
<Prop name="value" required type="number | undefined" sourceLineNumbers={[893]}>
Numeric value within safe integer range.
Valid range: `Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`
Invalid values:
* Infinity or -Infinity
* NaN
* Negative zero (-0)
* Denormalized numbers
Use `undefined` for an empty cell.
</Prop>
<Prop name="metadata" type="NumberCellMetadata" sourceLineNumbers={[905]}>
Optional formatting information for displaying the number.
<Prop.Extras>
**Example: Applying display formatting to a number**
```ts
import type { NumberCellMetadata } from '@canva/intents/data';
const currencyFormatting: NumberCellMetadata = { formatting: '[$USD]#,##0.00' };
const percentageFormatting: NumberCellMetadata = { formatting: '0.00%' };
```
</Prop.Extras>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>metadata</strong></>}>
<Prop.List>
<Prop name="formatting" type="string" sourceLineNumbers={[846]}>
Formatting pattern using Office Open XML Format.
These patterns control how numbers are displayed to users,
including currency symbols, decimal places, and separators.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="boolean">
Cell containing a boolean value.
<Prop.Extras>
**Examples**
**Creating a boolean cell**
```ts
import type { BooleanDataTableCell } from '@canva/intents/data';
const isActiveCell: BooleanDataTableCell = {
type: 'boolean',
value: true
};
```
**Creating a boolean cell with false value**
```ts
import type { BooleanDataTableCell } from '@canva/intents/data';
const isCompleteCell: BooleanDataTableCell = {
type: 'boolean',
value: false
};
```
**Creating an empty boolean cell**
```ts
import type { BooleanDataTableCell } from '@canva/intents/data';
const emptyBooleanCell: BooleanDataTableCell = {
type: 'boolean',
value: undefined
};
```
</Prop.Extras>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[124]}>
Indicates this cell contains a boolean value.
The only valid value is `"boolean"`.
</Prop>
<Prop name="value" required type="boolean | undefined" sourceLineNumbers={[130]}>
Boolean value (true or false).
Use `undefined` for an empty cell.
</Prop>
</Prop.List>
</Tab>
<Tab name="media">
Cell containing a media collection (images) value.
<Prop.Extras>
**Examples**
**Creating a media cell with an image**
```ts
import type { MediaCollectionDataTableCell } from '@canva/intents/data';
const mediaCell: MediaCollectionDataTableCell = {
type: 'media',
value: [{
type: 'image_upload',
url: 'https://www.canva.dev/example-assets/image-import/image.jpg',
mimeType: 'image/jpeg',
thumbnailUrl: 'https://www.canva.dev/example-assets/image-import/thumbnail.jpg',
aiDisclosure: 'none'
}]
};
```
**Creating an empty media cell**
```ts
import type { MediaCollectionDataTableCell } from '@canva/intents/data';
const emptyMediaCell: MediaCollectionDataTableCell = {
type: 'media',
value: []
};
```
</Prop.Extras>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[789]}>
Indicates this cell contains a media collection.
The only valid value is `"media"`.
</Prop>
<Prop name="value" required type="object[]" sourceLineNumbers={[795]}>
Media collection values.
Use empty array for an empty cell.
<Tabs>
<Tab name="DataTableImageUpload">
Options for uploading an image asset to the user's private media library.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[368]}>
Indicates this value contains options for image uploading.
The only valid value is `"image_upload"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[683]}>
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={[687]}>
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={[705]}>
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={[745]}>
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={[605]}>
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.List>
</Tab>
<Tab name="DataTableVideoUpload">
Options for uploading a video asset to the user's private media library.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[450]}>
Indicates this value contains options for video uploading.
The only valid value is `"video_upload"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[1151]}>
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={[1155]}>
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={[1187]}>
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={[1225]}>
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={[1126]}>
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="thumbnailVideoUrl" type="string" sourceLineNumbers={[1168]}>
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.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="columnConfigs" type="ColumnConfig[]" sourceLineNumbers={[339]}>
Column definitions with names and data types.
These help Canva interpret and display your data correctly.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>columnConfigs</strong></>}>
<Prop.List>
<Prop name="name" required type="string | undefined" sourceLineNumbers={[143]}>
Name for the column, displayed as header text.
If `undefined`, the column will have no header text.
</Prop>
<Prop name="type" required type="object" sourceLineNumbers={[150]}>
Expected data type for cells in this column.
Use a specific `DataType` for columns with consistent types,
or `'variant'` for columns that may contain mixed types.
<Tabs>
<Tab name="DataType">
Data types supported for table cells.
<Prop.Extras>
**Available values**:
* `"string"`
* `"number"`
* `"date"`
* `"boolean"`
* `"media"`
</Prop.Extras>
</Tab>
<Tab name="string">
The only valid value is `"variant"`.
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="metadata" type="DataTableMetadata" sourceLineNumbers={[522]}>
Optional metadata providing additional context about the data.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>metadata</strong></>}>
<Prop.List>
<Prop name="description" type="string" sourceLineNumbers={[400]}>
A human-readable description of the dataset.
This description helps users understand what data they are importing.
</Prop>
<Prop name="providerInfo" type="object" sourceLineNumbers={[404]}>
Information about the data provider or source.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>providerInfo</strong></>}>
<Prop.List>
<Prop name="name" required type="string" sourceLineNumbers={[408]}>
Name of the data provider.
</Prop>
<Prop name="url" type="string" sourceLineNumbers={[412]}>
URL to the provider's website or related resource.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="GetDataTableError">
Error results that can be returned from `getDataTable` method.
<Tabs>
<Tab name="OutdatedSourceRefError">
GetDataTableError indicating the data source reference is no longer valid.
This will trigger a re-selection flow for the user.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[927]}>
The data source reference is no longer valid.
Return this error when the DataSourceRef cannot be used to retrieve data,
for example:
* The referenced dataset has been deleted
* Access permissions have changed
* The structure of the data has fundamentally changed
This will trigger a re-selection flow, allowing the user to choose a new
data source.
The only valid value is `"outdated_source_ref"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="RemoteRequestFailedError">
GetDataTableError indicating failure to fetch data from the external source.
Typically due to network issues or API failures.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[986]}>
Failed to fetch data from the external source.
Return this error for network issues, API failures, or other
connectivity problems that prevent data retrieval.
The only valid value is `"remote_request_failed"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="AppError">
GetDataTableError indicating custom error occurred in the app's implementation.
This can be used to indicate specific issues that are not covered by other error types.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[54]}>
A custom error occurred in your app.
Return this for application-specific errors that don't fit
the other categories. Include a descriptive message explaining
the error to the user.
The only valid value is `"app_error"`.
</Prop>
<Prop name="message" type="string" sourceLineNumbers={[58]}>
Optional message explaining the error.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop>
<Prop name="renderSelectionUi" required type="function" sourceLineNumbers={[222]}>
Renders a user interface for selecting and configuring data from your external sources.
<Prop.Extras>
**Example: Rendering a data selection UI**
```ts
import type { RenderSelectionUiRequest } from '@canva/intents/data';
async function renderSelectionUi(request: RenderSelectionUiRequest): Promise<void> {
// UI rendering logic.
// Example: if user selects data 'ref123'.
const selectedRef = { source: 'ref123', title: 'My Selected Table' };
try {
const result = await request.updateDataRef(selectedRef);
if (result.status === 'completed') {
console.log('Selection valid and preview updated.');
} else {
console.error('Selection error:', result.status);
}
} catch (error) {
console.error('An unexpected error occurred during data ref update:', error);
}
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="request" required type="RenderSelectionUiRequest" sourceLineNumbers={[222]}>
Configuration and callbacks for the data selection UI.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="invocationContext" required type="InvocationContext" sourceLineNumbers={[1005]}>
Context information about why the data selection UI is being launched.
Use this to adapt your UI for different scenarios:
* 'data\_selection': Initial data selection or editing existing data
* 'outdated\_source\_ref': Previous reference is no longer valid, guide user to reselect
* 'app\_error': Custom error occurred, show error message and recovery options
When `dataSourceRef` is provided, pre-populate your UI with this selection.
<Tabs>
<Tab name="DataSelectionInvocationContext">
InvocationContext indicating initial data selection flow or edit of existing data.
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[241]}>
Initial data selection or editing existing data.
This is the standard flow when:
* A user is selecting data for the first time
* A user is editing a previous selection
If `dataSourceRef` is provided, this indicates an edit flow, and you should
pre-populate your UI with this selection.
The only valid value is `"data_selection"`.
</Prop>
<Prop name="dataSourceRef" type="DataSourceRef" sourceLineNumbers={[245]}>
If dataSourceRef is provided, this is an edit of existing data flow and UI should be pre-populated.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
<Prop.List>
<Prop name="source" required type="string" sourceLineNumbers={[282]}>
Information needed to identify and retrieve data from your source.
This string should contain all the information your app needs to
fetch the exact data selection later. Typically, this is a serialized
object with query parameters, identifiers, or filters.
You are responsible for encoding and decoding this value appropriately.
Maximum size: 5KB
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[291]}>
A human-readable description of the data reference.
This title may be displayed to users in the Canva interface to help
them identify the data source.
Maximum length: 255 characters
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="OutdatedSourceRefInvocationContext">
InvocationContext indicating an error occurred because the previously selected data source reference is no longer valid.
Triggered when getDataTable returned 'outdated\_source\_ref' during data refresh.
UI should guide the user to reselect or reconfigure their data.
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[946]}>
Previously selected data source reference is no longer valid.
This occurs when `getDataTable` returned 'outdated\_source\_ref' during a
refresh attempt. Your UI should guide the user to select a new data source
or update their selection.
The outdated reference is provided to help you suggest an appropriate replacement.
The only valid value is `"outdated_source_ref"`.
</Prop>
<Prop name="dataSourceRef" type="DataSourceRef" sourceLineNumbers={[950]}>
The outdated data source reference that caused the error during refresh.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
<Prop.List>
<Prop name="source" required type="string" sourceLineNumbers={[282]}>
Information needed to identify and retrieve data from your source.
This string should contain all the information your app needs to
fetch the exact data selection later. Typically, this is a serialized
object with query parameters, identifiers, or filters.
You are responsible for encoding and decoding this value appropriately.
Maximum size: 5KB
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[291]}>
A human-readable description of the data reference.
This title may be displayed to users in the Canva interface to help
them identify the data source.
Maximum length: 255 characters
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="AppErrorInvocationContext">
InvocationContext indicating a custom error occurred during data refresh.
Triggered when getDataTable returned 'app\_error' status.
UI should display the error message and help users recover.
<Prop.List>
<Prop name="reason" required type="string" sourceLineNumbers={[75]}>
A custom error occurred during data refresh.
This occurs when `getDataTable` returned 'app\_error' during a refresh attempt.
Your UI should display the error message and help users recover from the specific
issue.
The only valid value is `"app_error"`.
</Prop>
<Prop name="dataSourceRef" type="DataSourceRef" sourceLineNumbers={[79]}>
The data source reference that caused the error during refresh.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
<Prop.List>
<Prop name="source" required type="string" sourceLineNumbers={[282]}>
Information needed to identify and retrieve data from your source.
This string should contain all the information your app needs to
fetch the exact data selection later. Typically, this is a serialized
object with query parameters, identifiers, or filters.
You are responsible for encoding and decoding this value appropriately.
Maximum size: 5KB
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[291]}>
A human-readable description of the data reference.
This title may be displayed to users in the Canva interface to help
them identify the data source.
Maximum length: 255 characters
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="message" type="string" sourceLineNumbers={[83]}>
The error message to display to the user.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
<Prop name="limit" required type="DataTableLimit" sourceLineNumbers={[1013]}>
Maximum allowed rows and columns for the imported data.
Your UI should inform users of these constraints and prevent or warn about
selections that would exceed them. This helps users understand why certain
data sets might not be available for selection.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>limit</strong></>}>
<Prop.List>
<Prop name="row" required type="number" sourceLineNumbers={[381]}>
The maximum number of rows allowed.
Your app should ensure data does not exceed this limit.
</Prop>
<Prop name="column" required type="number" sourceLineNumbers={[387]}>
The maximum number of columns allowed.
Your app should ensure data does not exceed this limit.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="updateDataRef" required type="function" sourceLineNumbers={[1032]}>
Callback to preview selected data before finalizing import.
Call this function when the user selects data to:
1. Show a preview of the selected data to the user
2. Validate that the selection meets system requirements
Calling this function will trigger your `getDataTable` implementation.
Wait for the promise to resolve to determine if the selection is valid.
<Prop.Extras>
**Throws**
Will throw CanvaError('bad\_request') if
1. DataSourceRef.source exceeds 5kb.
2. DataSourceRef.title exceeds 255 characters.
3. GetDataTableCompleted.dataTable exceeds DataTableLimit or contains invalid data.
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="dataSourceRef" required type="DataSourceRef" sourceLineNumbers={[1032]}>
Reference object identifying the selected data
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
<Prop.List>
<Prop name="source" required type="string" sourceLineNumbers={[282]}>
Information needed to identify and retrieve data from your source.
This string should contain all the information your app needs to
fetch the exact data selection later. Typically, this is a serialized
object with query parameters, identifiers, or filters.
You are responsible for encoding and decoding this value appropriately.
Maximum size: 5KB
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[291]}>
A human-readable description of the data reference.
This title may be displayed to users in the Canva interface to help
them identify the data source.
Maximum length: 255 characters
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
Promise resolving to success or an error result. This is a `Promise` that resolves with the following object:
<Tabs>
<Tab name="UpdateDataRefCompleted">
Successful result from the RenderSelectionUiRequest.updateDataRef callback.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[1077]}>
The data selection was successful and can be previewed.
The only valid value is `"completed"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="GetDataTableError">
Error results that can be returned from `getDataTable` method.
<Tabs>
<Tab name="OutdatedSourceRefError">
GetDataTableError indicating the data source reference is no longer valid.
This will trigger a re-selection flow for the user.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[927]}>
The data source reference is no longer valid.
Return this error when the DataSourceRef cannot be used to retrieve data,
for example:
* The referenced dataset has been deleted
* Access permissions have changed
* The structure of the data has fundamentally changed
This will trigger a re-selection flow, allowing the user to choose a new
data source.
The only valid value is `"outdated_source_ref"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="RemoteRequestFailedError">
GetDataTableError indicating failure to fetch data from the external source.
Typically due to network issues or API failures.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[986]}>
Failed to fetch data from the external source.
Return this error for network issues, API failures, or other
connectivity problems that prevent data retrieval.
The only valid value is `"remote_request_failed"`.
</Prop>
</Prop.List>
</Tab>
<Tab name="AppError">
GetDataTableError indicating custom error occurred in the app's implementation.
This can be used to indicate specific issues that are not covered by other error types.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[54]}>
A custom error occurred in your app.
Return this for application-specific errors that don't fit
the other categories. Include a descriptive message explaining
the error to the user.
The only valid value is `"app_error"`.
</Prop>
<Prop name="message" type="string" sourceLineNumbers={[58]}>
Optional message explaining the error.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
void
Prepare Design Editor
API reference for the intents prepareDesignEditor method.
Prepares a DesignEditor Intent.
Usage
tsx
import { prepareDesignEditor } from '@canva/intents/design';
prepareDesignEditor({
render: async () => {
// TODO: Implement the logic to render your app's UI
},
});Parameters
<Prop.List> <Prop name="implementation" required type="DesignEditorIntent" sourceLineNumbers={[39]}> Main interface for implementing the DesignEditor intent.
Implementing the DesignEditor Intent enables apps to assist users in editing designs,
by presenting interactive and creative tooling alongside the Canva design surface.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>implementation</strong></>}>
<Prop.List>
<Prop name="render" required type="function" sourceLineNumbers={[20]}>
Renders the UI containing the app’s functionality.
<Prop.Extras>
**Example**
```tsx
function render() {
// render your UI using your preferred framework
}
```
</Prop.Extras>
**Returns**
`void`
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
void
Intents Changelog
The latest changes for the Canva Apps SDK @canva/intents package.
2.5.0 - 2026-04-09
Changed
- Increased the
publishRefsize limit from 5KB to 32KB, allowing apps to store more complex publishing settings.
Added
- Add selection metadata in MediaSelection
- Enable apps to support transparent PNG exports in publish flow by adding optional allowTransparentBackground capability to ImageRequirement
2.4.0 - 2026-03-23
Added
- Launch the new Email media type to public, enabling publishing and selection of email pages.
2.3.1 - 2026-03-12
Fixed
- Re-export data types from the intents/data public API that were accidentally removed during a refactor
- Rename
Selectiontype toMediaSelectionfor clarity
2.3.0 - 2026-03-06
Added
- Promoted
Selection,ImageSelection,VideoSelection,DocumentSelection,EmailSelectiontypes andMediaSlot.selectionfield from beta to public
2.2.0 - 2026-02-06
Added
- Added invocation context to provide initial state when rendering UIs
2.1.2 - 2026-02-03
Fixed
- Fix missing id and status fields in Content Publisher email preview type
2.1.1 - 2026-01-30
Changed
- Update NPM readme
2.1.0 - 2026-01-30
Added
- Added a CHANGELOG.md to track changes.
- Added a test harness method
initTestEnvionmentwhich can be imported from@canva/intents/test - Promoted the Content Publisher Intent API from beta to general availability
2.0.0 - 2025-06-12
Added
- Added the new
@canva/intentspackage at version2.0.0with the brand new Data Connector intent.