Appearance
Apps SDK — Preview API
Express Design Verify Token
API reference for the design.verifyToken method.
NOTE: This API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.
Usage: Extract design token from query parameter:
typescript
import { design, tokenExtractors } from '@canva/app-middleware/express';
app.get('/api/design/data', design.verifyToken({
appId: 'your-app-id',
tokenExtractor: tokenExtractors.fromQuery('design_token')
}), handler);Parameters
<Prop.List> <Prop name="options" required state="preview" type="DesignAuthOptions" sourceLineNumbers={[26]}> Configuration options
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="appId" required type="string" sourceLineNumbers={[31]}>
The ID of the Canva app, obtained via the developer portal canva.com/developers.
</Prop>
<Prop name="tokenExtractor" required state="preview" type="TokenExtractor" sourceLineNumbers={[20]}>
A function that extracts the design JWT token from the request.
Unlike user tokens, design tokens have no default extractor and must be
explicitly configured based on how your app passes the design token.
<Prop.Extras>
**Example**
```typescript
tokenExtractor: tokenExtractors.fromBearerAuth()
tokenExtractor: tokenExtractors.fromQuery('design_token')
tokenExtractor: tokenExtractors.fromHeader('X-Design-Token')
```
</Prop.Extras>
**Parameters**
<Prop.List />
**Returns**
<Tabs />
</Prop>
<Prop name="cacheMaxAgeMinutes" type="number" sourceLineNumbers={[36]}>
The maximum age of the JWKS cache in minutes.
<Prop.Extras>
**Default value**: `60`
</Prop.Extras>
</Prop>
<Prop name="timeoutMs" type="number" sourceLineNumbers={[41]}>
The timeout for the JWKS fetch in milliseconds.
<Prop.Extras>
**Default value**: `30000`
</Prop.Extras>
</Prop>
<Prop name="baseUrl" type="string" sourceLineNumbers={[46]}>
The base URL for the JWKS endpoint.
<Prop.Extras>
**Default value**: `"https://api.canva.com"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
Express middleware that verifies design JWT tokens.
RequestHandler
Init Design Token Verifier
API reference for the initDesignTokenVerifier method.
NOTE: This API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.
Initializes a design token verifier with the given configuration.
Design tokens are JWTs that identify a specific Canva design. They are used to verify requests that need access to design-specific data.
The verifier caches JWKS public keys according to the configured cache settings. Create one verifier instance and reuse it for all verification requests.
Usage
Basic usage:
typescript
import { initDesignTokenVerifier } from '@canva/app-middleware';
// Initialize once at app startup
const designTokenVerifier = initDesignTokenVerifier({
appId: process.env.CANVA_APP_ID,
});
// Verify tokens per request inside a handler
const payload = await designTokenVerifier.verify(token);
console.log(payload.designId, payload.appId);With custom options:
typescript
const designTokenVerifier = initDesignTokenVerifier({
appId: process.env.CANVA_APP_ID,
cacheMaxAgeMinutes: 30,
timeoutMs: 10000,
});Parameters
<Prop.List> <Prop name="options" required state="preview" type="TokenVerifierOptions" sourceLineNumbers={[41]}> Configuration options for the verifier
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="appId" required type="string" sourceLineNumbers={[31]}>
The ID of the Canva app, obtained via the developer portal canva.com/developers.
</Prop>
<Prop name="cacheMaxAgeMinutes" type="number" sourceLineNumbers={[36]}>
The maximum age of the JWKS cache in minutes.
<Prop.Extras>
**Default value**: `60`
</Prop.Extras>
</Prop>
<Prop name="timeoutMs" type="number" sourceLineNumbers={[41]}>
The timeout for the JWKS fetch in milliseconds.
<Prop.Extras>
**Default value**: `30000`
</Prop.Extras>
</Prop>
<Prop name="baseUrl" type="string" sourceLineNumbers={[46]}>
The base URL for the JWKS endpoint.
<Prop.Extras>
**Default value**: `"https://api.canva.com"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
A configured verifier instance.
<Prop.List> <Prop name="verify" required type="function" sourceLineNumbers={[86]}> Verifies a Canva design JWT token and returns the decoded payload.
**Parameters**
<Prop.List>
<Prop name="token" required type="string" sourceLineNumbers={[86]}>
The JWT token to verify
</Prop>
</Prop.List>
**Returns**
The verified design token payload. This is a `Promise` that resolves with the following object:
<Prop.List>
<Prop name="appId" required type="string" sourceLineNumbers={[19]}>
The ID of the Canva app
</Prop>
<Prop name="designId" required type="string" sourceLineNumbers={[21]}>
The ID of the Canva design
</Prop>
</Prop.List>
<Prop.Extras>
**Throws**
When the token is malformed or has an invalid signature
**Throws**
When the token has expired
</Prop.Extras>
</Prop> </Prop.List>
Token Verification Error
API reference for the TokenVerificationError method.
NOTE: This API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.
Base class for all token verification errors. All token verification errors extend this class.
Constructors
<Prop.List> <Prop name="constructor" required type="function" sourceLineNumbers={[24]}> ### Constructor
#### Parameters
<Prop.List>
<Prop name="code" required state="preview" type="ErrorCode" sourceLineNumbers={[24]}>
An error code that identifies why an error was thrown by the app middleware.
<Prop.Extras>
**Available values**:
* `"TOKEN_MISSING"`
* `"TOKEN_EXPIRED"`
* `"TOKEN_INVALID"`
</Prop.Extras>
</Prop>
</Prop.List>
</Prop> </Prop.List>
Properties
<Prop.List> <Prop name="code" required state="preview" readonly type="ErrorCode" sourceLineNumbers={[21]}> Machine-readable error code
<Prop.Extras>
**Available values**:
* `"TOKEN_MISSING"`
* `"TOKEN_EXPIRED"`
* `"TOKEN_INVALID"`
</Prop.Extras>
</Prop>
<Prop name="statusCode" required state="preview" readonly type="number" sourceLineNumbers={[23]}> HTTP status code to use when responding to the client </Prop> </Prop.List>
Methods
<Prop.List> <Prop name="[hasInstance]" required type="function" sourceLineNumbers={[17]}> Parameters
<Prop.List />
**Returns**
`instance is TokenVerificationError`
</Prop> </Prop.List>
App Middleware Changelog
The latest changes for the Canva Apps SDK @canva/app-middleware@beta package.
v0.0.0-beta.5 - 2026-01-22
Added
- Added design token authentication support with
initDesignTokenVerifier()core function anddesign.verifyToken()Express middleware for verifying design-scoped requests.
Changed
- Renamed
UserAuthErrortoTokenVerificationError.
v0.0.0-beta.4 - 2026-01-15
Changed
- Dependencies audit bringing modules up to date:
text
jsonwebtoken 9.0.2 -> 9.0.3Removed
- Removed unused
AppIdMismatchErrorclass, which was never thrown.
v0.0.0-beta.3 - 2026-01-13
Changed
- Replaced
@publicwith@betatags in TSDocs, while the SDK's still in beta.
v0.0.0-beta.2 - 2025-12-23
Added
- Added new
UserTokenVerifiertype for theexpress/usernamespace.
Changed
- Various examples and documentation improvements in TSDocs.
Fixed
- Fixed an issue where
err instanceOf UserAuthErrorchecks were failing across cjs/esm module boundaries. - Ensured error messages are logged in debug mode.
- Token verification now only checks for claims that exist in the token.
v0.0.0-beta.1 - 2025-12-22
Added
- Initial release of
@canva/app-middleware.
Design Edit Content (Preview)
API reference for the editContent method.
NOTE: This API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.
Reads and edits content from the user's design.
Parameters
<Prop.List> <Prop name="options" required type="object" sourceLineNumbers={[3130]}> Options for configuring how a design is read. Must specify a content type.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="target" required type="string" sourceLineNumbers={[1102]}>
The only valid value is `"current_page"`.
</Prop>
<Prop name="contentType" required type="T" sourceLineNumbers={[3131]}>
<Prop.Extras>
**Available values**:
* `"richtext"`
* `"fill"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="callback" required type="function" sourceLineNumbers={[3130]}> A callback that receives a session for editing.
**Parameters**
<Prop.List>
<Prop name="session" required type="object" sourceLineNumbers={[3132]}>
<Tabs>
<Tab name="richtext">
A callback for reading and updating the requested design content.
<Prop.Extras>
**Param: session**
The result of reading the content in the design.
**Examples**
**Read and update richtext content**
```typescript
import { editContent } from "@canva/design";
await editContent(
{ contentType: 'richtext', target: 'current_page' },
async (session) => {
// Read the content
const contents = session.contents;
if (contents.length > 0) {
const range = contents[0];
// Modify the content (e.g., adding text)
range.appendText("\nAppended text from app");
// Sync changes back to the design
await session.sync();
}
}
);
```
**Format all richtext content in the design**
```typescript
import { editContent } from "@canva/design";
await editContent(
{ contentType: 'richtext', target: 'current_page' },
async (session) => {
// Process each richtext range in the content
for (const range of session.contents) {
// Skip if the content has been deleted
if (range.deleted) continue;
// Get the text content
const text = range.readPlaintext();
if (text.length === 0) continue;
// Apply consistent formatting
range.formatParagraph(
{ index: 0, length: text.length },
{
fontRef: 'YOUR_FONT_REF',
fontSize: 16,
textAlign: 'start'
}
);
}
// Sync all changes back to the design
await session.sync();
}
);
```
**Modify content without saving changes**
```typescript
import { editContent } from "@canva/design";
await editContent(
{ contentType: 'richtext', target: 'current_page' },
async (session) => {
// Read and analyze the content without making changes
for (const range of session.contents) {
const text = range.readPlaintext();
// Do something with the content preview, e.g. `text.substring(0, 50)`
// No call to session.sync() means no changes are saved
}
// Since we're not calling sync(), no changes will be made to the design
}
);
```
</Prop.Extras>
<Prop.List>
<Prop name="contents" required readonly type="RichtextContentRange[]" sourceLineNumbers={[4294]}>
Richtext content in the design.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>contents</strong></>}>
<Prop.List>
<Prop name="deleted" required readonly type="boolean" sourceLineNumbers={[4206]}>
Indicates whether the object containing this richtext range has been deleted.
</Prop>
<Prop name="formatParagraph" required type="function" sourceLineNumbers={[4447]}>
Formats all of the paragraphs that overlap the given bounds.
* The `\n` character indicates the end of a paragraph.
* All paragraphs that overlap the provided bounds will be formatted in their entirety.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4447]}>
The segment of the range on which to apply the formatting.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[889]}>
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
</Prop>
<Prop name="length" required type="number" sourceLineNumbers={[893]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4447]}>
The formatting to apply to the paragraph(s).
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3807]}>
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a `#` symbol.
<Prop.Extras>
**Example**
```ts
"#ff0099"
```
</Prop.Extras>
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[3816]}>
The weight (thickness) of the font.
The available font weights depend on the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"thin"`
* `"extralight"`
* `"light"`
* `"medium"`
* `"semibold"`
* `"bold"`
* `"ultrabold"`
* `"heavy"`
</Prop.Extras>
</Prop>
<Prop name="fontStyle" type="string" sourceLineNumbers={[3821]}>
The style of the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"italic"`
</Prop.Extras>
</Prop>
<Prop name="decoration" type="string" sourceLineNumbers={[3826]}>
The decoration of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="strikethrough" type="string" sourceLineNumbers={[3831]}>
The strikethrough of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"strikethrough"`
</Prop.Extras>
</Prop>
<Prop name="link" type="string" sourceLineNumbers={[3835]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4365]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4374]}>
The size of the text, in pixels.
* In the Canva editor, this number is shown as points (pts), not pixels.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4379]}>
The alignment of the text.
<Prop.Extras>
**Default value**: `"start"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"start"`
* `"center"`
* `"end"`
* `"justify"`
</Prop.Extras>
</Prop>
<Prop name="listLevel" type="number" sourceLineNumbers={[4383]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4392]}>
The appearance of list item markers.
This property only has an effect if `listLevel` is greater than 0.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"disc"`
* `"circle"`
* `"square"`
* `"decimal"`
* `"lower-alpha"`
* `"lower-roman"`
* `"checked"`
* `"unchecked"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
<Prop.Extras>
**Examples**
**Format paragraph as a heading**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("Heading Text\nRegular paragraph text.");
// Format just the first paragraph as a heading
range.formatParagraph(
{ index: 0, length: 12 }, // Only need to include part of the paragraph
{
fontSize: 24,
fontWeight: 'bold',
textAlign: 'center'
}
);
```
**Create a bulleted list**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
const text = "Item 1\nItem 2\nItem 3";
range.appendText(text);
// Format all paragraphs as a bulleted list
range.formatParagraph(
{ index: 0, length: text.length },
{
listLevel: 1,
listMarker: 'disc'
}
);
```
</Prop.Extras>
</Prop>
<Prop name="formatText" required type="function" sourceLineNumbers={[4489]}>
Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4489]}>
The segment of the range on which to apply the formatting.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[889]}>
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
</Prop>
<Prop name="length" required type="number" sourceLineNumbers={[893]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4489]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3807]}>
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a `#` symbol.
<Prop.Extras>
**Example**
```ts
"#ff0099"
```
</Prop.Extras>
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[3816]}>
The weight (thickness) of the font.
The available font weights depend on the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"thin"`
* `"extralight"`
* `"light"`
* `"medium"`
* `"semibold"`
* `"bold"`
* `"ultrabold"`
* `"heavy"`
</Prop.Extras>
</Prop>
<Prop name="fontStyle" type="string" sourceLineNumbers={[3821]}>
The style of the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"italic"`
</Prop.Extras>
</Prop>
<Prop name="decoration" type="string" sourceLineNumbers={[3826]}>
The decoration of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="strikethrough" type="string" sourceLineNumbers={[3831]}>
The strikethrough of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"strikethrough"`
</Prop.Extras>
</Prop>
<Prop name="link" type="string" sourceLineNumbers={[3835]}>
An external URL that the text links to.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
<Prop.Extras>
**Examples**
**Format specific words in a paragraph**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("This text contains important information.");
// Format just the word "important"
range.formatText(
{ index: 16, length: 9 },
{
fontWeight: 'bold',
color: '#FF0000'
}
);
```
**Add a link to text**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("Visit our website for more information.");
// Add a link to "our website"
range.formatText(
{ index: 6, length: 11 },
{
link: "https://www.example.com",
decoration: 'underline',
color: '#0066CC'
}
);
```
</Prop.Extras>
</Prop>
<Prop name="appendText" required type="function" sourceLineNumbers={[4527]}>
Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4527]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4527]}>
Optional formatting to apply to the appended text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3807]}>
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a `#` symbol.
<Prop.Extras>
**Example**
```ts
"#ff0099"
```
</Prop.Extras>
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[3816]}>
The weight (thickness) of the font.
The available font weights depend on the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"thin"`
* `"extralight"`
* `"light"`
* `"medium"`
* `"semibold"`
* `"bold"`
* `"ultrabold"`
* `"heavy"`
</Prop.Extras>
</Prop>
<Prop name="fontStyle" type="string" sourceLineNumbers={[3821]}>
The style of the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"italic"`
</Prop.Extras>
</Prop>
<Prop name="decoration" type="string" sourceLineNumbers={[3826]}>
The decoration of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="strikethrough" type="string" sourceLineNumbers={[3831]}>
The strikethrough of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"strikethrough"`
</Prop.Extras>
</Prop>
<Prop name="link" type="string" sourceLineNumbers={[3835]}>
An external URL that the text links to.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4528]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[889]}>
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
</Prop>
<Prop name="length" required type="number" sourceLineNumbers={[893]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
<Prop.Extras>
**Examples**
**Append plain text**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("First paragraph. ");
// Append more text to the existing content
const result = range.appendText("This is additional text.");
// The bounds of the newly added text are returned
// Do something with the bounds - result.bounds, e.g. { index: 17, length: 24 }
```
**Append formatted text**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("Normal text followed by ");
// Append formatted text
range.appendText("bold red text", {
fontWeight: 'bold',
color: '#FF0000'
});
// Append a new paragraph
range.appendText("\nThis is a new paragraph.");
```
</Prop.Extras>
</Prop>
<Prop name="replaceText" required type="function" sourceLineNumbers={[4573]}>
Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4573]}>
The segment of the range to replace.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[889]}>
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
</Prop>
<Prop name="length" required type="number" sourceLineNumbers={[893]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4573]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4573]}>
The formatting to apply to the replaced text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3807]}>
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a `#` symbol.
<Prop.Extras>
**Example**
```ts
"#ff0099"
```
</Prop.Extras>
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[3816]}>
The weight (thickness) of the font.
The available font weights depend on the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"thin"`
* `"extralight"`
* `"light"`
* `"medium"`
* `"semibold"`
* `"bold"`
* `"ultrabold"`
* `"heavy"`
</Prop.Extras>
</Prop>
<Prop name="fontStyle" type="string" sourceLineNumbers={[3821]}>
The style of the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"italic"`
</Prop.Extras>
</Prop>
<Prop name="decoration" type="string" sourceLineNumbers={[3826]}>
The decoration of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="strikethrough" type="string" sourceLineNumbers={[3831]}>
The strikethrough of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"strikethrough"`
</Prop.Extras>
</Prop>
<Prop name="link" type="string" sourceLineNumbers={[3835]}>
An external URL that the text links to.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4577]}>
The bounds of the replacement characters within the updated range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[889]}>
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
</Prop>
<Prop name="length" required type="number" sourceLineNumbers={[893]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
<Prop.Extras>
**Examples**
**Replace text while maintaining some formatting**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("This text needs correction.");
// Replace "needs correction" with "is correct"
const result = range.replaceText(
{ index: 10, length: 16 },
"is correct"
);
// The bounds of the replaced text are returned
// Do something with the bounds - result.bounds, e.g. { index: 10, length: 10 }
```
**Replace text with formatted text**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("Regular text that needs emphasis.");
// Replace "needs emphasis" with formatted text
range.replaceText(
{ index: 17, length: 15 },
"is important",
{
fontWeight: 'bold',
fontStyle: 'italic',
color: '#0066CC'
}
);
```
</Prop.Extras>
</Prop>
<Prop name="readPlaintext" required type="function" sourceLineNumbers={[4616]}>
Returns the current state of the richtext as plaintext.
**Returns**
`string`
<Prop.Extras>
**Examples**
**Extract plain text content**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("First paragraph.\n", { fontWeight: 'bold' });
range.appendText("Second paragraph with formatting.", { color: '#FF0000' });
// Get plain text content without formatting
const plainText = range.readPlaintext();
// Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting."
```
**Search within text content**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("This text contains a searchable term.");
// Search for a specific word
const plainText = range.readPlaintext();
const searchTerm = "searchable";
const index = plainText.indexOf(searchTerm);
if (index !== -1) {
// Format the found term
range.formatText(
{ index, length: searchTerm.length },
{ fontWeight: 'bold', decoration: 'underline' }
);
}
```
</Prop.Extras>
</Prop>
<Prop name="readTextRegions" required type="function" sourceLineNumbers={[4663]}>
Returns the current state of the richtext as one or more text regions.
Each region is an object that contains the text content and its formatting.
**Returns**
<Prop.List>
<Prop name="text" required type="string" sourceLineNumbers={[5146]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[5150]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3807]}>
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a `#` symbol.
<Prop.Extras>
**Example**
```ts
"#ff0099"
```
</Prop.Extras>
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[3816]}>
The weight (thickness) of the font.
The available font weights depend on the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"thin"`
* `"extralight"`
* `"light"`
* `"medium"`
* `"semibold"`
* `"bold"`
* `"ultrabold"`
* `"heavy"`
</Prop.Extras>
</Prop>
<Prop name="fontStyle" type="string" sourceLineNumbers={[3821]}>
The style of the font.
<Prop.Extras>
**Default value**: `"normal"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"normal"`
* `"italic"`
</Prop.Extras>
</Prop>
<Prop name="decoration" type="string" sourceLineNumbers={[3826]}>
The decoration of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="strikethrough" type="string" sourceLineNumbers={[3831]}>
The strikethrough of the text.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"strikethrough"`
</Prop.Extras>
</Prop>
<Prop name="link" type="string" sourceLineNumbers={[3835]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4365]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4374]}>
The size of the text, in pixels.
* In the Canva editor, this number is shown as points (pts), not pixels.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4379]}>
The alignment of the text.
<Prop.Extras>
**Default value**: `"start"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"start"`
* `"center"`
* `"end"`
* `"justify"`
</Prop.Extras>
</Prop>
<Prop name="listLevel" type="number" sourceLineNumbers={[4383]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4392]}>
The appearance of list item markers.
This property only has an effect if `listLevel` is greater than 0.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"disc"`
* `"circle"`
* `"square"`
* `"decimal"`
* `"lower-alpha"`
* `"lower-roman"`
* `"checked"`
* `"unchecked"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
<Prop.Extras>
**Examples**
**Get text with formatting information**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("Normal text ", {});
range.appendText("bold text", { fontWeight: 'bold' });
range.appendText(" and ", {});
range.appendText("red text", { color: '#FF0000' });
// Get formatted regions
const regions = range.readTextRegions();
// Do something with the regions, e.g.
// [
// { text: "Normal text ", formatting: {} },
// { text: "bold text", formatting: { fontWeight: 'bold' } },
// { text: " and ", formatting: {} },
// { text: "red text", formatting: { color: '#FF0000' } }
// ]
```
**Analyze formatting variations**
```typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("Mixed ", {});
range.appendText("formatted ", { fontWeight: 'bold' });
range.appendText("text", { color: '#0066CC' });
// Analyze formatting variations
const regions = range.readTextRegions();
const formattingTypes = regions.map(region => {
const formatting = region.formatting || {};
return {
text: region.text,
hasWeight: !!formatting.fontWeight,
hasColor: !!formatting.color
};
});
```
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="sync" required type="function" sourceLineNumbers={[4326]}>
Saves any changes made during the session while keeping the transaction open.
* Any changes in the session are only reflected in the design after this method is called.
* Once this method is called, further changes in the session can still be made.
**Returns**
`Promise<void>`
<Prop.Extras>
**Example: Sync changes after modifying content**
```typescript
import { editContent } from "@canva/design";
await editContent(
{ contentType: 'richtext', target: 'current_page' },
async (session) => {
if (session.contents.length > 0) {
const range = session.contents[0];
// Make modifications to the content
range.appendText(" - Modified by app");
try {
// Save changes back to the design
await session.sync();
} catch (error) {
console.error('Failed to sync changes:', error);
}
}
}
);
```
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="fill" icon={<StateIndicator state="preview" />}>
Session for reading and updating fill content in a user's design.
<Prop.List>
<Prop name="contents" required state="preview" readonly type="FillContent[]" sourceLineNumbers={[3472]}>
Fill content in the design.
<Tabs>
<Tab name="image">
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3429]}>
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3433]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="deleted" required type="boolean" sourceLineNumbers={[3444]}>
Indicates whether the object containing this fill has been deleted.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3440]}>
A description of the image content.
Use `undefined` for content with no description.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>altText</strong></>}>
<Prop.List>
<Prop name="text" required type="string" sourceLineNumbers={[397]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[405]}>
Indicates where the alternative text should be displayed.
* If `true`, the alternative text will only be displayed in the editor.
* If `false`, the alternative text will be displayed in the editor and in view-only mode.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="video">
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3446]}>
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[3450]}>
A unique identifier that points to an video asset in Canva's backend.
</Prop>
<Prop name="deleted" required type="boolean" sourceLineNumbers={[3461]}>
Indicates whether the object containing this fill has been deleted.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3457]}>
A description of the video content.
Use `undefined` for content with no description.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>altText</strong></>}>
<Prop.List>
<Prop name="text" required type="string" sourceLineNumbers={[397]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[405]}>
Indicates where the alternative text should be displayed.
* If `true`, the alternative text will only be displayed in the editor.
* If `false`, the alternative text will be displayed in the editor and in view-only mode.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
<Prop name="sync" required type="function" sourceLineNumbers={[3480]}>
* Any changes in the session are only reflected in the design after this method is called.
* Once this method is called, further changes in the session can still be made.
**Returns**
`Promise<void>`
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
**Returns**
`void` or `Promise<void>`
</Prop> </Prop.List>
Returns
A promise that resolves when editing is complete.
Promise<void>
Get Design Template Metadata
API reference for the getDesignTemplateMetadata method.
NOTE: This API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.
Retrieves information about the template that was used in a design.
Usage: Get design template metadata
typescript
import { getDesignTemplateMetadata } from "@canva/design";
const templateMetadata = await getDesignTemplateMetadata();
const { keywords, domain } = templateMetadata;Returns
Information about the template that was used in a design. This is a Promise that resolves with the following object:
<Prop.List> <Prop name="templates" type="Iterable<TemplateMetadata>" sourceLineNumbers={[3067]}> The templates applied to the pages within the design.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>templates</strong></>}>
<Prop.List>
<Prop name="keywords" required type="string[]" sourceLineNumbers={[5000]}>
A list of keywords contained in a template.
</Prop>
<Prop name="domain" required type="string" sourceLineNumbers={[5004]}>
Determines the domain of the template. This could be public, brand or personal.
<Prop.Extras>
**Available values**:
* `"public"`
* `"brand"`
* `"personal"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Features Is Supported
API reference for the features.isSupported method.
Checks if the specified SDK methods are supported in the current context.
Usage
Checking a single feature
typescript
import { features } from '@canva/platform';
import { addElementAtPoint } from '@canva/design';
const isSupported = features.isSupported(addElementAtPoint);Checking multiple features
typescript
import { features } from '@canva/platform';
import { addElementAtPoint, addElementAtCursor } from '@canva/design';
const areSupported = features.isSupported(addElementAtPoint, addElementAtCursor);Parameters
<Prop.List> <Prop name="features" required type="Feature[]" sourceLineNumbers={[417]}> The SDK methods to be checked for support. </Prop> </Prop.List>
Returns
boolean
Add Toast (Preview)
API reference for the notification.addToast method.
A method that shows a toast notification to the user.
Usage
tsx
import { notification } from '@canva/platform';
import type { ToastRequest } from '@canva/platform';
const showToast = () => {
const request: ToastRequest = {
messageText: "Hello world!",
};
notification.addToast(request);
};
<Button onClick={() => showToast()}>Show Toast</Button>Parameters
<Prop.List> <Prop name="request" required type="ToastRequest" sourceLineNumbers={[499]}> Options for configuring a toast notification.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="messageText" required type="string" sourceLineNumbers={[684]}>
Text to show within the toast notification.
</Prop>
<Prop name="timeoutMs" type="number | string" sourceLineNumbers={[694]}>
The duration that the notification will be visible.
If set to `"infinite"`, the notification will be displayed until manually dismissed by the user.
If set to a number, the notification will automatically disappear after that duration (in milliseconds).
<Prop.Extras>
**Default value**: `5000`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
The result when a toast notification is successfully added. This is a Promise that resolves with the following object:
<Prop.List> <Prop name="status" required type="string" sourceLineNumbers={[672]}> The status of the request.
The only valid value is `"completed"`.
</Prop> </Prop.List>