Appearance
Apps SDK — Design API
Add Page
API reference for the addPage method.
Adds a new page immediately after the currently selected page.
Usage
Create empty page
typescript
import { addPage } from "@canva/design";
await addPage();Create page with title
typescript
import { addPage } from "@canva/design";
await addPage({
title: 'My New Page'
});Create page with background color
typescript
import { addPage } from "@canva/design";
import type { PageBackgroundFill } from "@canva/design";
const background: PageBackgroundFill = {
color: '#F5F5F5',
};
await addPage({ background });Create page with background image
typescript
import { addPage } from "@canva/design";
import type { PageBackgroundFill } from "@canva/design";
import type { ImageRef } from "@canva/asset";
const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
const background: PageBackgroundFill = {
asset: {
type: 'image',
ref: exampleImageRef,
altText: { text: 'Background image', decorative: true }
},
};
await addPage({ background });Create page with multiple elements
typescript
import { addPage } from "@canva/design";
import type { TextElementAtPoint, ImageElementAtPoint } from "@canva/design";
import type { ImageRef } from "@canva/asset";
const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
await addPage({
elements: [
{
type: 'text',
children: ['Page Title'],
top: 50,
left: 100,
width: 400,
fontSize: 32,
textAlign: 'center'
} as TextElementAtPoint,
{
type: 'text',
children: ['Subtitle text'],
top: 100,
left: 100,
width: 400,
fontSize: 18,
textAlign: 'center'
} as TextElementAtPoint,
{
type: 'image',
ref: exampleImageRef,
altText: { text: 'Featured image', decorative: false },
top: 150,
left: 200,
width: 200,
height: 200
} as ImageElementAtPoint,
]
});Create page with custom dimensions
typescript
import { addPage } from "@canva/design";
await addPage({
dimensions: {
width: 300,
height: 300,
},
});Parameters
<Prop.List> <Prop name="opts" type="object" sourceLineNumbers={[346]}> Configuration for the new page to be added.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="elements" type="ElementAtPoint[]" sourceLineNumbers={[348]}>
Elements to be added to the page.
<Tabs>
<Tab name="Images">
An element that renders image content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3393]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[3400]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="dataUrl" type="string" sourceLineNumbers={[3405]}>
A data URL that contains the image data.
</Prop>
<Prop name="ref" type="ImageRef" sourceLineNumbers={[3419]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
An element that renders video content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4940]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4944]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[4951]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Embeds">
An element that renders rich media, such as a YouTube video, and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2986]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[2993]}>
The URL of the rich media.
This URL must be supported by the Iframely API.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Text">
An element that renders text content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4816]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" required type="string[]" sourceLineNumbers={[4823]}>
The text content.
Only the first element in this array is used.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="width" type="number" sourceLineNumbers={[4769]}>
The width of the element, in pixels.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Shapes">
An element that renders a vector shape and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4605]}>
The type of element.
The only valid value is `"shape"`.
</Prop>
<Prop name="viewBox" required type="ShapeViewBox" sourceLineNumbers={[4609]}>
Options for configuring the scale and cropping of the shape.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>viewBox</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[4667]}>
The distance of the shape from the top edge of the element, in pixels.
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[4671]}>
The distance of the shape from the left edge of the element, in pixels.
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[4675]}>
The width of the view box, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[4679]}>
The height of the view box, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="paths" required type="ShapePath[]" sourceLineNumbers={[4618]}>
The paths that define the structure of the shape.
* There must be between 1 and 30 paths (inclusive).
* The maximum combined size of all paths must not exceed 2kb.
* The maximum number of unique fill colors across all paths is 6.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>paths</strong></>}>
<Prop.List>
<Prop name="d" required type="string" sourceLineNumbers={[4645]}>
The shape of the path.
This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
* The path must start with an M command.
* The path must not have more than one M command.
* The path must not use the Q command.
* The path must be closed, either by:
* Using a Z command at the end of the path
* Having the last coordinate match the first coordinate
</Prop>
<Prop name="fill" required type="Fill" sourceLineNumbers={[4649]}>
The appearance of the path's interior.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fill</strong></>}>
<Prop.List>
<Prop name="dropTarget" type="boolean" sourceLineNumbers={[3177]}>
If `true`, users can replace a fill by dropping an image or video onto it.
</Prop>
<Prop name="color" type="string" sourceLineNumbers={[3187]}>
The color of the fill 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="asset" type="object" sourceLineNumbers={[3191]}>
An image or video to use as the fill.
<Tabs>
<Tab name="Images">
An image asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3436]}>
The type of fill.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3440]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3447]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Videos">
A video asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4968]}>
The type of fill.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4972]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[4979]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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.List>
</PillAccordion>
</Prop>
<Prop name="stroke" type="PathStroke" sourceLineNumbers={[4653]}>
The outline of the path.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>stroke</strong></>}>
<Prop.List>
<Prop name="weight" required type="number" sourceLineNumbers={[3811]}>
The weight (thickness) of the stroke.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `100`
</Prop.Extras>
</Prop>
<Prop name="color" required type="string" sourceLineNumbers={[3821]}>
The color of the stroke 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="strokeAlign" required type="string" sourceLineNumbers={[3825]}>
The alignment of the stroke.
The only valid value is `"inset"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Groups">
An element that contains two or more elements and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3337]}>
The type of element.
The only valid value is `"group"`.
</Prop>
<Prop name="children" required type="GroupContentAtPoint[]" sourceLineNumbers={[3345]}>
The elements to render within the group.
* Each element within a group must have dimensions and a position.
* The dimensions and positions are relative to the dimensions and positions of the group.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Richtext">
An element that renders richtext content.
This type includes properties for controlling the position and dimensions of the
element.
It will be positioned and sized relative to its parent container.
The parent container may be an app element, or the current page.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4050]}>
The type of element.
The only valid value is `"richtext"`.
</Prop>
<Prop name="range" required type="RichtextRange" sourceLineNumbers={[4054]}>
The richtext content.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>range</strong></>}>
<Prop.List>
<Prop name="formatParagraph" required type="function" sourceLineNumbers={[4160]}>
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={[4160]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4160]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4202]}>
Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4202]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4202]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4240]}>
Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4240]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4240]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4241]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[865]}>
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={[869]}>
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={[4286]}>
Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4286]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4286]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4286]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4290]}>
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={[865]}>
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={[869]}>
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={[4329]}>
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={[4376]}>
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={[4840]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[4844]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="width" type="number" sourceLineNumbers={[4769]}>
The width of the element, in pixels.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
<Prop name="background" type="PageBackgroundFill" sourceLineNumbers={[350]}>
The page background. This can be a solid color, an image or a video.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>background</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3187]}>
The color of the fill 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="asset" type="object" sourceLineNumbers={[3191]}>
An image or video to use as the fill.
<Tabs>
<Tab name="Images">
An image asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3436]}>
The type of fill.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3440]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3447]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Videos">
A video asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4968]}>
The type of fill.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4972]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[4979]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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.List>
</PillAccordion>
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[352]}>
A page title which must be no longer than 255 characters
</Prop>
<Prop name="dimensions" type="object" sourceLineNumbers={[359]}>
The optional custom dimensions in pixels for the new page. The following constraints apply:
* `width` and `height` cannot be lower than 40 or higher than 8000
* The total area of the new page cannot exceed 25\_000\_000
In case this is not specified, the default dimensions for the design type will be used.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dimensions</strong></>}>
<Prop.List />
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
Promise<void>
Add Element at Cursor
API reference for the addElementAtCursor method.
Add element to responsive documents, which slot things into a text stream
Usage
Insert an image at cursor position
typescript
import { addElementAtCursor } from "@canva/design";
import type { ImageElement } from "@canva/design";
import type { ImageRef } from "@canva/asset";
const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
const imageElement: ImageElement = {
type: 'image',
ref: exampleImageRef,
altText: { text: 'Product image', decorative: false }
};
await addElementAtCursor(imageElement);Insert a video at cursor position
typescript
import { addElementAtCursor } from "@canva/design";
import type { VideoElement } from "@canva/design";
import type { VideoRef } from "@canva/asset";
const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;
const videoElement: VideoElement = {
type: 'video',
ref: exampleVideoRef,
altText: { text: 'Product demo', decorative: false }
};
await addElementAtCursor(videoElement);Insert embedded content at cursor position
typescript
import { addElementAtCursor } from "@canva/design";
import type { EmbedElement } from "@canva/design";
const embedElement: EmbedElement = {
type: 'embed',
url: 'https://www.youtube.com/watch?v=...'
};
await addElementAtCursor(embedElement);Insert text at cursor position
typescript
import { addElementAtCursor } from "@canva/design";
import type { TextElement } from "@canva/design";
const textElement: TextElement = {
type: 'text',
children: ['Hello World'],
fontSize: 24,
color: '#000000'
};
await addElementAtCursor(textElement);Insert formatted text at cursor position
typescript
import { addElementAtCursor, createRichtextRange } from "@canva/design";
import type { RichtextElement } from "@canva/design";
const range = createRichtextRange();
range.appendText('Rich Text Content', { color: '#000000' });
const richtextElement: RichtextElement = {
type: 'richtext',
range
};
await addElementAtCursor(richtextElement);Insert a table at cursor position
typescript
import { addElementAtCursor } from "@canva/design";
import type { TableElement } from "@canva/design";
const tableElement: TableElement = {
type: 'table',
rows: [
{
cells: [
{ type: 'string', value: 'Header 1' },
{ type: 'string', value: 'Header 2' }
]
},
{
cells: [
{ type: 'string', value: 'Data 1' },
{ type: 'string', value: 'Data 2' }
]
}
]
};
await addElementAtCursor(tableElement);Parameters
<Prop.List> <Prop name="element" required type="ElementAtCursor" sourceLineNumbers={[131]}> Elements targeting a cursor are a subset of the base Element
<Tabs>
<Tab name="Images">
An element that renders image content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3393]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[3400]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="dataUrl" type="string" sourceLineNumbers={[3405]}>
A data URL that contains the image data.
</Prop>
<Prop name="ref" type="ImageRef" sourceLineNumbers={[3419]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
An element that renders video content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4940]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4944]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[4951]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Embeds">
An element that renders rich media, such as a YouTube video.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2986]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[2993]}>
The URL of the rich media.
This URL must be supported by the Iframely API.
</Prop>
</Prop.List>
</Tab>
<Tab name="Text">
An element that renders text content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4816]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" required type="string[]" sourceLineNumbers={[4823]}>
The text content.
Only the first element in this array is used.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Richtext">
An element that renders richtext content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4050]}>
The type of element.
The only valid value is `"richtext"`.
</Prop>
<Prop name="range" required type="RichtextRange" sourceLineNumbers={[4054]}>
The richtext content.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>range</strong></>}>
<Prop.List>
<Prop name="formatParagraph" required type="function" sourceLineNumbers={[4160]}>
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={[4160]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4160]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4202]}>
Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4202]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4202]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4240]}>
Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4240]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4240]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4241]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[865]}>
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={[869]}>
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={[4286]}>
Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4286]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4286]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4286]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4290]}>
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={[865]}>
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={[869]}>
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={[4329]}>
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={[4376]}>
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={[4840]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[4844]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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.List>
</Tab>
<Tab name="Tables">
An element that renders a table.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4690]}>
The type of element.
The only valid value is `"table"`.
</Prop>
<Prop name="rows" required type="object[]" sourceLineNumbers={[4694]}>
The rows of the table.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>rows</strong></>}>
<Prop.List>
<Prop name="cells" required type="Array<Cell | null | undefined>" sourceLineNumbers={[4701]}>
The cells (columns) of the row.
Each row must have the same number of cells.
This should be either the following object, `null`, or `undefined`.
<Prop.List>
<Prop name="attributes" type="CellAttributes" sourceLineNumbers={[920]}>
The attributes of the cell.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>attributes</strong></>}>
<Prop.List>
<Prop name="backgroundColor" type="string" sourceLineNumbers={[939]}>
The background color of the cell, as a hex code.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="colSpan" type="number" sourceLineNumbers={[924]}>
The number of columns that the cell occupies.
</Prop>
<Prop name="rowSpan" type="number" sourceLineNumbers={[928]}>
The number of rows that the cell occupies.
</Prop>
<Prop name="type" required type="string" sourceLineNumbers={[951]}>
<Prop.Extras>
**Available values**:
* `"empty"`
* `"string"`
</Prop.Extras>
</Prop>
<Prop name="value" required="Required if `type` is string" type="string" sourceLineNumbers={[963]}>
The plaintext content of the cell.
If an empty string is provided, the `type` will change to `"empty"`.
</Prop>
</Prop.List>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
Promise<void>
Add Element at Point
API reference for the addElementAtPoint method.
Add element to fixed designs, which use a coordinate-based positioning system.
Usage
Insert an image at specific coordinates
typescript
import { addElementAtPoint } from "@canva/design";
import type { ImageElementAtPoint } from "@canva/design";
import type { ImageRef } from "@canva/asset";
const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
const imageElement: ImageElementAtPoint = {
type: 'image',
ref: exampleImageRef,
altText: { text: 'Product image', decorative: false },
top: 100,
left: 100,
width: 300,
height: 200
};
await addElementAtPoint(imageElement);Insert a video at specific coordinates
typescript
import { addElementAtPoint } from "@canva/design";
import type { VideoElementAtPoint } from "@canva/design";
import type { VideoRef } from "@canva/asset";
const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;
const videoElement: VideoElementAtPoint = {
type: 'video',
ref: exampleVideoRef,
altText: { text: 'Product demo', decorative: false },
top: 100,
left: 100,
width: 400,
height: 300
};
await addElementAtPoint(videoElement);Insert embedded content at specific coordinates
typescript
import { addElementAtPoint } from "@canva/design";
import type { EmbedElementAtPoint } from "@canva/design";
const embedElement: EmbedElementAtPoint = {
type: 'embed',
url: 'https://www.youtube.com/watch?v=...',
top: 100,
left: 100,
width: 560,
height: 315
};
await addElementAtPoint(embedElement);Insert text at specific coordinates
typescript
import { addElementAtPoint } from "@canva/design";
import type { TextElementAtPoint } from "@canva/design";
const textElement: TextElementAtPoint = {
type: 'text',
children: ['Hello World'],
top: 100,
left: 100,
width: 200,
fontSize: 24,
color: '#000000',
textAlign: 'justify'
};
await addElementAtPoint(textElement);Parameters
<Prop.List> <Prop name="element" required type="object" sourceLineNumbers={[215]}> <Tabs> <Tab name="DesignElement"> An element that's natively supported by the Canva editor.
<Tabs>
<Tab name="Images">
An element that renders image content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3393]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[3400]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="dataUrl" type="string" sourceLineNumbers={[3405]}>
A data URL that contains the image data.
</Prop>
<Prop name="ref" type="ImageRef" sourceLineNumbers={[3419]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
An element that renders video content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4940]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4944]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[4951]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Embeds">
An element that renders rich media, such as a YouTube video.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2986]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[2993]}>
The URL of the rich media.
This URL must be supported by the Iframely API.
</Prop>
</Prop.List>
</Tab>
<Tab name="Text">
An element that renders text content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4816]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" required type="string[]" sourceLineNumbers={[4823]}>
The text content.
Only the first element in this array is used.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Shapes">
An element that renders a vector shape.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4605]}>
The type of element.
The only valid value is `"shape"`.
</Prop>
<Prop name="viewBox" required type="ShapeViewBox" sourceLineNumbers={[4609]}>
Options for configuring the scale and cropping of the shape.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>viewBox</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[4667]}>
The distance of the shape from the top edge of the element, in pixels.
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[4671]}>
The distance of the shape from the left edge of the element, in pixels.
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[4675]}>
The width of the view box, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[4679]}>
The height of the view box, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="paths" required type="ShapePath[]" sourceLineNumbers={[4618]}>
The paths that define the structure of the shape.
* There must be between 1 and 30 paths (inclusive).
* The maximum combined size of all paths must not exceed 2kb.
* The maximum number of unique fill colors across all paths is 6.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>paths</strong></>}>
<Prop.List>
<Prop name="d" required type="string" sourceLineNumbers={[4645]}>
The shape of the path.
This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
* The path must start with an M command.
* The path must not have more than one M command.
* The path must not use the Q command.
* The path must be closed, either by:
* Using a Z command at the end of the path
* Having the last coordinate match the first coordinate
</Prop>
<Prop name="fill" required type="Fill" sourceLineNumbers={[4649]}>
The appearance of the path's interior.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fill</strong></>}>
<Prop.List>
<Prop name="dropTarget" type="boolean" sourceLineNumbers={[3177]}>
If `true`, users can replace a fill by dropping an image or video onto it.
</Prop>
<Prop name="color" type="string" sourceLineNumbers={[3187]}>
The color of the fill 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="asset" type="object" sourceLineNumbers={[3191]}>
An image or video to use as the fill.
<Tabs>
<Tab name="Images">
An image asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3436]}>
The type of fill.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3440]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3447]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Videos">
A video asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4968]}>
The type of fill.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4972]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[4979]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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.List>
</PillAccordion>
</Prop>
<Prop name="stroke" type="PathStroke" sourceLineNumbers={[4653]}>
The outline of the path.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>stroke</strong></>}>
<Prop.List>
<Prop name="weight" required type="number" sourceLineNumbers={[3811]}>
The weight (thickness) of the stroke.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `100`
</Prop.Extras>
</Prop>
<Prop name="color" required type="string" sourceLineNumbers={[3821]}>
The color of the stroke 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="strokeAlign" required type="string" sourceLineNumbers={[3825]}>
The alignment of the stroke.
The only valid value is `"inset"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="Groups">
An element that contains two or more elements.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3337]}>
The type of element.
The only valid value is `"group"`.
</Prop>
<Prop name="children" required type="GroupContentAtPoint[]" sourceLineNumbers={[3345]}>
The elements to render within the group.
* Each element within a group must have dimensions and a position.
* The dimensions and positions are relative to the dimensions and positions of the group.
</Prop>
</Prop.List>
</Tab>
<Tab name="Richtext">
An element that renders richtext content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4050]}>
The type of element.
The only valid value is `"richtext"`.
</Prop>
<Prop name="range" required type="RichtextRange" sourceLineNumbers={[4054]}>
The richtext content.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>range</strong></>}>
<Prop.List>
<Prop name="formatParagraph" required type="function" sourceLineNumbers={[4160]}>
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={[4160]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4160]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4202]}>
Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4202]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4202]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4240]}>
Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4240]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4240]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4241]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[865]}>
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={[869]}>
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={[4286]}>
Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4286]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4286]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4286]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4290]}>
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={[865]}>
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={[869]}>
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={[4329]}>
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={[4376]}>
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={[4840]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[4844]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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.List>
</Tab>
<Tab name="Tables">
An element that renders a table.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4690]}>
The type of element.
The only valid value is `"table"`.
</Prop>
<Prop name="rows" required type="object[]" sourceLineNumbers={[4694]}>
The rows of the table.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>rows</strong></>}>
<Prop.List>
<Prop name="cells" required type="Array<Cell | null | undefined>" sourceLineNumbers={[4701]}>
The cells (columns) of the row.
Each row must have the same number of cells.
This should be either the following object, `null`, or `undefined`.
<Prop.List>
<Prop name="attributes" type="CellAttributes" sourceLineNumbers={[920]}>
The attributes of the cell.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>attributes</strong></>}>
<Prop.List>
<Prop name="backgroundColor" type="string" sourceLineNumbers={[939]}>
The background color of the cell, as a hex code.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="colSpan" type="number" sourceLineNumbers={[924]}>
The number of columns that the cell occupies.
</Prop>
<Prop name="rowSpan" type="number" sourceLineNumbers={[928]}>
The number of rows that the cell occupies.
</Prop>
<Prop name="type" required type="string" sourceLineNumbers={[951]}>
<Prop.Extras>
**Available values**:
* `"empty"`
* `"string"`
</Prop.Extras>
</Prop>
<Prop name="value" required="Required if `type` is string" type="string" sourceLineNumbers={[963]}>
The plaintext content of the cell.
If an empty string is provided, the `type` will change to `"empty"`.
</Prop>
</Prop.List>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="ElementAtPoint">
An element that's natively supported by the Canva editor and has positional properties.
<Tabs>
<Tab name="Images">
An element that renders image content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3393]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[3400]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="dataUrl" type="string" sourceLineNumbers={[3405]}>
A data URL that contains the image data.
</Prop>
<Prop name="ref" type="ImageRef" sourceLineNumbers={[3419]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
An element that renders video content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4940]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4944]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[4951]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Embeds">
An element that renders rich media, such as a YouTube video, and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2986]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[2993]}>
The URL of the rich media.
This URL must be supported by the Iframely API.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Text">
An element that renders text content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4816]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" required type="string[]" sourceLineNumbers={[4823]}>
The text content.
Only the first element in this array is used.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="width" type="number" sourceLineNumbers={[4769]}>
The width of the element, in pixels.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Shapes">
An element that renders a vector shape and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4605]}>
The type of element.
The only valid value is `"shape"`.
</Prop>
<Prop name="viewBox" required type="ShapeViewBox" sourceLineNumbers={[4609]}>
Options for configuring the scale and cropping of the shape.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>viewBox</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[4667]}>
The distance of the shape from the top edge of the element, in pixels.
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[4671]}>
The distance of the shape from the left edge of the element, in pixels.
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[4675]}>
The width of the view box, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[4679]}>
The height of the view box, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="paths" required type="ShapePath[]" sourceLineNumbers={[4618]}>
The paths that define the structure of the shape.
* There must be between 1 and 30 paths (inclusive).
* The maximum combined size of all paths must not exceed 2kb.
* The maximum number of unique fill colors across all paths is 6.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>paths</strong></>}>
<Prop.List>
<Prop name="d" required type="string" sourceLineNumbers={[4645]}>
The shape of the path.
This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
* The path must start with an M command.
* The path must not have more than one M command.
* The path must not use the Q command.
* The path must be closed, either by:
* Using a Z command at the end of the path
* Having the last coordinate match the first coordinate
</Prop>
<Prop name="fill" required type="Fill" sourceLineNumbers={[4649]}>
The appearance of the path's interior.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fill</strong></>}>
<Prop.List>
<Prop name="dropTarget" type="boolean" sourceLineNumbers={[3177]}>
If `true`, users can replace a fill by dropping an image or video onto it.
</Prop>
<Prop name="color" type="string" sourceLineNumbers={[3187]}>
The color of the fill 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="asset" type="object" sourceLineNumbers={[3191]}>
An image or video to use as the fill.
<Tabs>
<Tab name="Images">
An image asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3436]}>
The type of fill.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3440]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3447]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Videos">
A video asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4968]}>
The type of fill.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4972]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[4979]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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.List>
</PillAccordion>
</Prop>
<Prop name="stroke" type="PathStroke" sourceLineNumbers={[4653]}>
The outline of the path.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>stroke</strong></>}>
<Prop.List>
<Prop name="weight" required type="number" sourceLineNumbers={[3811]}>
The weight (thickness) of the stroke.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `100`
</Prop.Extras>
</Prop>
<Prop name="color" required type="string" sourceLineNumbers={[3821]}>
The color of the stroke 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="strokeAlign" required type="string" sourceLineNumbers={[3825]}>
The alignment of the stroke.
The only valid value is `"inset"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Groups">
An element that contains two or more elements and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3337]}>
The type of element.
The only valid value is `"group"`.
</Prop>
<Prop name="children" required type="GroupContentAtPoint[]" sourceLineNumbers={[3345]}>
The elements to render within the group.
* Each element within a group must have dimensions and a position.
* The dimensions and positions are relative to the dimensions and positions of the group.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Richtext">
An element that renders richtext content.
This type includes properties for controlling the position and dimensions of the
element.
It will be positioned and sized relative to its parent container.
The parent container may be an app element, or the current page.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4050]}>
The type of element.
The only valid value is `"richtext"`.
</Prop>
<Prop name="range" required type="RichtextRange" sourceLineNumbers={[4054]}>
The richtext content.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>range</strong></>}>
<Prop.List>
<Prop name="formatParagraph" required type="function" sourceLineNumbers={[4160]}>
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={[4160]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4160]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4202]}>
Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4202]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4202]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4240]}>
Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4240]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4240]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4241]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[865]}>
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={[869]}>
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={[4286]}>
Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4286]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4286]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4286]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4290]}>
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={[865]}>
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={[869]}>
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={[4329]}>
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={[4376]}>
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={[4840]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[4844]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="width" type="number" sourceLineNumbers={[4769]}>
The width of the element, in pixels.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
Promise<void>
Add Native Element
API reference for the addNativeElement method.
WARNING: This API is deprecated, and is no longer recommended for use, and should be removed from your app.
Adds a native element to the user's design.
Usage: Basic usage
typescript
import { addNativeElement } from "@canva/design";
import type { NativeElementWithBox } from "@canva/design";
const element: NativeElementWithBox = {
type: 'text',
children: ['Legacy element'],
top: 100,
left: 100,
width: 200
};
await addNativeElement(element);Parameters
<Prop.List> <Prop name="element" required type="object" sourceLineNumbers={[239]}> The element to add to the user's design.
<Tabs>
<Tab name="NativeElement" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `DesignElement`.
An element that's natively supported by the Canva editor.
<Tabs>
<Tab name="Images" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `ImageElement`.
An element that renders image content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3393]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[3400]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="dataUrl" type="string" sourceLineNumbers={[3405]}>
A data URL that contains the image data.
</Prop>
<Prop name="ref" type="ImageRef" sourceLineNumbers={[3419]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `VideoElement`.
An element that renders video content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4940]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4944]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[4951]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Embeds" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `EmbedElement`.
An element that renders rich media, such as a YouTube video.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2986]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[2993]}>
The URL of the rich media.
This URL must be supported by the Iframely API.
</Prop>
</Prop.List>
</Tab>
<Tab name="Text" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `TextElement`.
An element that renders text content.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4816]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" required type="string[]" sourceLineNumbers={[4823]}>
The text content.
Only the first element in this array is used.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Shapes" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `ShapeElement`.
An element that renders a vector shape.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4605]}>
The type of element.
The only valid value is `"shape"`.
</Prop>
<Prop name="viewBox" required type="ShapeViewBox" sourceLineNumbers={[4609]}>
Options for configuring the scale and cropping of the shape.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>viewBox</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[4667]}>
The distance of the shape from the top edge of the element, in pixels.
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[4671]}>
The distance of the shape from the left edge of the element, in pixels.
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[4675]}>
The width of the view box, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[4679]}>
The height of the view box, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="paths" required type="ShapePath[]" sourceLineNumbers={[4618]}>
The paths that define the structure of the shape.
* There must be between 1 and 30 paths (inclusive).
* The maximum combined size of all paths must not exceed 2kb.
* The maximum number of unique fill colors across all paths is 6.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>paths</strong></>}>
<Prop.List>
<Prop name="d" required type="string" sourceLineNumbers={[4645]}>
The shape of the path.
This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
* The path must start with an M command.
* The path must not have more than one M command.
* The path must not use the Q command.
* The path must be closed, either by:
* Using a Z command at the end of the path
* Having the last coordinate match the first coordinate
</Prop>
<Prop name="fill" required type="Fill" sourceLineNumbers={[4649]}>
The appearance of the path's interior.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fill</strong></>}>
<Prop.List>
<Prop name="dropTarget" type="boolean" sourceLineNumbers={[3177]}>
If `true`, users can replace a fill by dropping an image or video onto it.
</Prop>
<Prop name="color" type="string" sourceLineNumbers={[3187]}>
The color of the fill 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="asset" type="object" sourceLineNumbers={[3191]}>
An image or video to use as the fill.
<Tabs>
<Tab name="Images">
An image asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3436]}>
The type of fill.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3440]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3447]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Videos">
A video asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4968]}>
The type of fill.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4972]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[4979]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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.List>
</PillAccordion>
</Prop>
<Prop name="stroke" type="PathStroke" sourceLineNumbers={[4653]}>
The outline of the path.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>stroke</strong></>}>
<Prop.List>
<Prop name="weight" required type="number" sourceLineNumbers={[3811]}>
The weight (thickness) of the stroke.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `100`
</Prop.Extras>
</Prop>
<Prop name="color" required type="string" sourceLineNumbers={[3821]}>
The color of the stroke 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="strokeAlign" required type="string" sourceLineNumbers={[3825]}>
The alignment of the stroke.
The only valid value is `"inset"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="Groups" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `GroupElement`.
An element that contains two or more elements.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3337]}>
The type of element.
The only valid value is `"group"`.
</Prop>
<Prop name="children" required type="GroupContentAtPoint[]" sourceLineNumbers={[3345]}>
The elements to render within the group.
* Each element within a group must have dimensions and a position.
* The dimensions and positions are relative to the dimensions and positions of the group.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
<Tab name="NativeElementWithBox" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `ElementAtPoint`.
An element that's natively supported by the Canva editor and has positional properties.
<Tabs>
<Tab name="Images" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `ImageElementAtPoint`.
An element that renders image content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3393]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[3400]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="dataUrl" type="string" sourceLineNumbers={[3405]}>
A data URL that contains the image data.
</Prop>
<Prop name="ref" type="ImageRef" sourceLineNumbers={[3419]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `VideoElementAtPoint`.
An element that renders video content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4940]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4944]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[4951]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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 name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Embeds" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `EmbedElementAtPoint`.
An element that renders rich media, such as a YouTube video, and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2986]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="url" required type="string" sourceLineNumbers={[2993]}>
The URL of the rich media.
This URL must be supported by the Iframely API.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Text" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `TextElementAtPoint`.
An element that renders text content and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4816]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" required type="string[]" sourceLineNumbers={[4823]}>
The text content.
Only the first element in this array is used.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4719]}>
The size of the text.
<Prop.Extras>
**Minimum**: `1`
**Maximum**: `100`
**Default value**: `16`
</Prop.Extras>
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4724]}>
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="color" type="string" sourceLineNumbers={[4734]}>
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="fontRef" type="FontRef" sourceLineNumbers={[4739]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4744]}>
The weight (thickness) of 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={[4749]}>
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={[4754]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
<Prop name="width" type="number" sourceLineNumbers={[4769]}>
The width of the element, in pixels.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Shapes" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `ShapeElementAtPoint`.
An element that renders a vector shape and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4605]}>
The type of element.
The only valid value is `"shape"`.
</Prop>
<Prop name="viewBox" required type="ShapeViewBox" sourceLineNumbers={[4609]}>
Options for configuring the scale and cropping of the shape.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>viewBox</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[4667]}>
The distance of the shape from the top edge of the element, in pixels.
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[4671]}>
The distance of the shape from the left edge of the element, in pixels.
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[4675]}>
The width of the view box, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[4679]}>
The height of the view box, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="paths" required type="ShapePath[]" sourceLineNumbers={[4618]}>
The paths that define the structure of the shape.
* There must be between 1 and 30 paths (inclusive).
* The maximum combined size of all paths must not exceed 2kb.
* The maximum number of unique fill colors across all paths is 6.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>paths</strong></>}>
<Prop.List>
<Prop name="d" required type="string" sourceLineNumbers={[4645]}>
The shape of the path.
This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
* The path must start with an M command.
* The path must not have more than one M command.
* The path must not use the Q command.
* The path must be closed, either by:
* Using a Z command at the end of the path
* Having the last coordinate match the first coordinate
</Prop>
<Prop name="fill" required type="Fill" sourceLineNumbers={[4649]}>
The appearance of the path's interior.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fill</strong></>}>
<Prop.List>
<Prop name="dropTarget" type="boolean" sourceLineNumbers={[3177]}>
If `true`, users can replace a fill by dropping an image or video onto it.
</Prop>
<Prop name="color" type="string" sourceLineNumbers={[3187]}>
The color of the fill 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="asset" type="object" sourceLineNumbers={[3191]}>
An image or video to use as the fill.
<Tabs>
<Tab name="Images">
An image asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3436]}>
The type of fill.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3440]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3447]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Videos">
A video asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4968]}>
The type of fill.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4972]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[4979]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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.List>
</PillAccordion>
</Prop>
<Prop name="stroke" type="PathStroke" sourceLineNumbers={[4653]}>
The outline of the path.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>stroke</strong></>}>
<Prop.List>
<Prop name="weight" required type="number" sourceLineNumbers={[3811]}>
The weight (thickness) of the stroke.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `100`
</Prop.Extras>
</Prop>
<Prop name="color" required type="string" sourceLineNumbers={[3821]}>
The color of the stroke 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="strokeAlign" required type="string" sourceLineNumbers={[3825]}>
The alignment of the stroke.
The only valid value is `"inset"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Groups" icon={<StateIndicator state="deprecated" />}>
The type has been superseded by `GroupElementAtPoint`.
An element that contains two or more elements and has positional properties.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3337]}>
The type of element.
The only valid value is `"group"`.
</Prop>
<Prop name="children" required type="GroupContentAtPoint[]" sourceLineNumbers={[3345]}>
The elements to render within the group.
* Each element within a group must have dimensions and a position.
* The dimensions and positions are relative to the dimensions and positions of the group.
</Prop>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
Promise<void>
Add Audio Track
API reference for the addAudioTrack method.
Adds an audio track to the user's design.
Usage: Add audio track to design
typescript
import { addAudioTrack } from "@canva/design";
import type { AudioTrack } from "@canva/design";
import type { AudioRef } from "@canva/asset";
const exampleAudioRef = "YOUR_AUDIO_REF" as AudioRef;
const audioTrack: AudioTrack = {
ref: exampleAudioRef
};
await addAudioTrack(audioTrack);Parameters
<Prop.List> <Prop name="audioTrack" required type="AudioTrack" sourceLineNumbers={[21]}> The audio track to add to the user's design.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>audioTrack</strong></>}>
<Prop.List>
<Prop name="ref" required type="AudioRef" sourceLineNumbers={[851]}>
A unique identifier that points to an audio asset in Canva's backend.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
Promise<void>
Edit Content
API reference for the editContent method.
Reads and edits content of the specified type from the user's design.
Usage: Read richtext content
typescript
import { editContent } from "@canva/design";
await editContent(
{ contentType: 'richtext', target: 'current_page' },
async (session) => {
// Do something with the richtext content, e.g. `session.contents`
}
);Parameters
<Prop.List> <Prop name="options" required type="EditContentOptions" sourceLineNumbers={[2920]}> Options for configuring how a design is read.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="contentType" required type="string" sourceLineNumbers={[2937]}>
The type of content to edit from the user's design
The only valid value is `"richtext"`.
</Prop>
<Prop name="target" required type="string" sourceLineNumbers={[1065]}>
The only valid value is `"current_page"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="callback" required type="EditContentCallback" sourceLineNumbers={[2920]}> A callback for operating on the read content.
**Parameters**
<Prop.List>
<Prop name="session" required type="RichtextContentSession" sourceLineNumbers={[2927]}>
The result of reading the content in the design.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>session</strong></>}>
<Prop.List>
<Prop name="contents" required readonly type="RichtextContentRange[]" sourceLineNumbers={[4007]}>
Richtext content in the design.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>contents</strong></>}>
<Prop.List>
<Prop name="deleted" required readonly type="boolean" sourceLineNumbers={[3919]}>
Indicates whether the object containing this richtext range has been deleted.
</Prop>
<Prop name="formatParagraph" required type="function" sourceLineNumbers={[4160]}>
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={[4160]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4160]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4202]}>
Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4202]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4202]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4240]}>
Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4240]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4240]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4241]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[865]}>
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={[869]}>
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={[4286]}>
Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4286]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4286]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4286]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4290]}>
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={[865]}>
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={[869]}>
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={[4329]}>
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={[4376]}>
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={[4840]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[4844]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4039]}>
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>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void` or `Promise<void>`
</Prop> </Prop.List>
Returns
Promise<void>
Create Richtext Range
API reference for the createRichtextRange method.
Creates a new RichtextRange object, which contains methods to manipulate text.
Usage
Create formatted text range
typescript
import { createRichtextRange } from "@canva/design";
import type { InlineFormatting } from "@canva/design";
const range = createRichtextRange();
range.appendText('Hello World', {
color: '#000000',
fontWeight: 'bold'
} as InlineFormatting);Format paragraph styles
typescript
import { createRichtextRange } from "@canva/design";
import type { RichtextFormatting } from "@canva/design";
const range = createRichtextRange();
const bounds = range.appendText('Centered Title\n');
range.formatParagraph(bounds.bounds, {
fontSize: 32,
textAlign: 'center'
} as RichtextFormatting);Create bulleted list
typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
const item = range.appendText('List item\n');
range.formatParagraph(item.bounds, {
fontSize: 16,
listLevel: 1,
listMarker: 'disc'
});Extract text content
typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText('Sample text');
// Get plain text content
const text = range.readPlaintext();
// Get formatted regions
const regions = range.readTextRegions();Replace text with formatting
typescript
import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText('Original text');
// Replace text while adding formatting
range.replaceText(
{ index: 0, length: range.readPlaintext().length },
'Modified',
{ color: '#0066CC', decoration: 'underline' }
);Returns
Provides methods for interacting with a range of formatted text.
<Prop.List> <Prop name="formatParagraph" required type="function" sourceLineNumbers={[4160]}> 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={[4160]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4160]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4202]}> Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4202]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4202]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4240]}> Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4240]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4240]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4241]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[865]}>
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={[869]}>
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={[4286]}> Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4286]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4286]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4286]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4290]}>
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={[865]}>
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={[869]}>
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={[4329]}> 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={[4376]}> 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={[4840]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[4844]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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>
Get Current Page Context
API reference for the getCurrentPageContext method.
Allows to get the context of currently selected page.
Usage: Get current page information
typescript
import { getCurrentPageContext } from "@canva/design";
const pageContext = await getCurrentPageContext();
if (pageContext.dimensions) {
// Do something with the page dimensions, e.g. `pageContext.dimensions.width` and `pageContext.dimensions.height`
} else {
// This page type does not have fixed dimensions, e.g. Whiteboard or Doc
}Returns
Page context of currently selected page. This is a Promise that resolves with the following object:
<Prop.List> <Prop name="dimensions" required type="PageDimensions | undefined" sourceLineNumbers={[3765]}> The dimensions of the page, in pixels.
This may be `undefined` because some types of pages don't have dimensions, such as whiteboards.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dimensions</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[3776]}>
The width of the page, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[3780]}>
The height of the page, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Get Default Page Dimensions
API reference for the getDefaultPageDimensions method.
WARNING: This API is deprecated, and is no longer recommended for use, and should be removed from your app.
Gets the default dimensions that a new page will have when it is added to a design. It is possible for a user to resize a page without resizing the entire design, e.g. by clicking "Expand to Whiteboard". However, there will always be a single set of default dimensions for a design that is applied whenever a new page is created.
Returns undefined if the design is unbounded (e.g. Whiteboard or Doc).
Usage
Get default page dimensions
typescript
import { getDefaultPageDimensions } from "@canva/design";
const dimensions = await getDefaultPageDimensions();
if (dimensions) {
// Do something with the dimensions, e.g. `dimensions.width` and `dimensions.height`
} else {
// This design type does not have fixed dimensions, e.g. Whiteboard or Doc
}Center element using page dimensions
typescript
import { getDefaultPageDimensions, addElementAtPoint } from "@canva/design";
import type { ImageElementAtPoint } from "@canva/design";
const dimensions = await getDefaultPageDimensions();
if (dimensions) {
const elementWidth = 300;
const elementHeight = 200;
const element: ImageElementAtPoint = {
type: 'image',
dataUrl: 'data:image/png;base64,...',
altText: { text: 'Centered image', decorative: false },
top: (dimensions.height - elementHeight) / 2,
left: (dimensions.width - elementWidth) / 2,
width: elementWidth,
height: elementHeight
};
await addElementAtPoint(element);
}Returns
A Promise that resolves with either undefined or the following object:
<Prop.List> <Prop name="width" required type="number" sourceLineNumbers={[2887]}> A width, in pixels. </Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}> A height, in pixels. </Prop> </Prop.List>
Get Design Metadata
API reference for the getDesignMetadata method.
Retrieves information about the design.
Usage: Get design metadata
typescript
import { getDesignMetadata } from "@canva/design";
const metadata = await getDesignMetadata();
const { title, defaultPageDimensions, pageMetadata, durationInSeconds } = metadata;Returns
Information about the design. This is a Promise that resolves with the following object:
<Prop.List> <Prop name="pageMetadata" required type="Iterable<PageMetadata>" sourceLineNumbers={[2619]}> The information associated with each page of the design.
The order of pages is not guaranteed.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>pageMetadata</strong></>}>
<Prop.List>
<Prop name="dimensions" type="PageDimensions" sourceLineNumbers={[3796]}>
The dimensions of the page, in pixels.
This may be `undefined` because some types of pages don't have dimensions, such as whiteboards.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>dimensions</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[3776]}>
The width of the page, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[3780]}>
The height of the page, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="durationInSeconds" required type="number" sourceLineNumbers={[2625]}> The duration of the whole design in seconds.
This is the precise value, which differs from what is displayed in the UI as duration in Canva UI is formatted differently.
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[2604]}> The title of the user's design.
This is optional and will be `undefined` if the user hasn't set a title.
</Prop>
<Prop name="defaultPageDimensions" type="PageDimensions" sourceLineNumbers={[2613]}> The default dimensions that a new page will have when it is added to a design. It is possible for a user to resize a page without resizing the entire design, e.g. by clicking "Expand to Whiteboard". However, there will always be a single set of default dimensions for a design that is applied whenever a new page is created.
This is optional and will be `undefined` if the design is unbounded (e.g. Whiteboard or Doc).
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>defaultPageDimensions</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[3776]}>
The width of the page, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[3780]}>
The height of the page, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Get Design Token
API reference for the getDesignToken method.
Retrieves a signed JWT that contains the Design ID, App ID and User ID.
Usage
Get design token
typescript
import { getDesignToken } from "@canva/design";
const { token } = await getDesignToken();Verify token with backend service
typescript
import { getDesignToken } from "@canva/design";
const { token } = await getDesignToken();
const verifyResponse = await fetch('https://your-backend.com/verify', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ token })
});
const json = await verifyResponse.json();
const { designId, appId, userId } = json;Returns
JWT that contains the Design ID and App ID. This is a Promise that resolves with the following object:
<Prop.List />
Init App Element
API reference for the initAppElement method.
Usage
Initialize app element client
typescript
import { initAppElement } from "@canva/design";
const appElement = initAppElement<{ content: string }>({
render: (data) => {
return [{
type: 'text',
children: [data.content],
top: 100,
left: 100,
width: 200
}];
}
});Initialize V2 app element client
typescript
import { initAppElement } from "@canva/design";
const appElement = initAppElement<{ content: string }>({
render: (data) => {
return [{
type: 'text',
children: [data.content],
top: 100,
left: 100,
width: 200
}];
}
});Parameters
<Prop.List> <Prop name="appElementConfig" required type="AppElementClientConfiguration<A>" sourceLineNumbers={[3496]}> Configuration for an AppElementClient
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>appElementConfig</strong></>}>
<Prop.List>
<Prop name="render" required type="AppElementRenderer<A>" sourceLineNumbers={[764]}>
Registers a callback that renders an app element based on the data it receives.
**Parameters**
<Prop.List>
<Prop name="appElementData" required type="A" sourceLineNumbers={[794]}>
The data the callback must use to render the app element.
<Tabs>
<Tab name="Primitive">
A primitive data type that can be used in app element data.
All primitive data types are supported except for symbols and bigints.
</Tab>
<Tab name="ObjectPrimitive">
An object primitive data type that can be used in app element data.
<Tabs />
</Tab>
</Tabs>
</Prop>
</Prop.List>
**Returns**
An array of one or more elements to render as output of an app element.
`AppElementRendererOutput`
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
A client that provides methods for creating and managing the lifecycle of an app element.
<Prop.List> <Prop name="addOrUpdateElement" required type="function" sourceLineNumbers={[585]}> This type has been superseded, use addElement or registerOnElementChange instead. If an app element is selected, the element's data is overwritten and the element is re-rendered. Otherwise, the provided data is used to create a new app element.
**Parameters**
<Prop.List>
<Prop name="appElementData" required type="A" sourceLineNumbers={[585]}>
The data to attach to the app element. Existing data will be overwritten.
<Tabs>
<Tab name="Primitive">
A primitive data type that can be used in app element data.
All primitive data types are supported except for symbols and bigints.
</Tab>
<Tab name="ObjectPrimitive">
An object primitive data type that can be used in app element data.
<Tabs />
</Tab>
</Tabs>
</Prop>
<Prop name="placement" type="Placement" sourceLineNumbers={[585]}>
The position, dimensions, and rotation of the app element.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>placement</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`Promise<void>`
<Prop.Extras>
**Examples**
**Create or update an element (deprecated)**
```typescript
import { initAppElement } from "@canva/design";
// Initialize the app element client
const appElement = initAppElement<{ content: string; timestamp: number }>({
render: (data) => {
return [{
type: 'text',
children: [data.content || 'Default text'],
top: 100,
left: 100,
width: 200
}];
}
});
// Create a new element or update selected element
await appElement.addOrUpdateElement({
content: 'Hello from the app',
timestamp: Date.now()
});
```
**Update with specific placement (deprecated)**
```typescript
import { initAppElement } from "@canva/design";
const appElement = initAppElement<{ content: string }>({
render: (data) => {
return [{
type: 'text',
children: [data.content || 'Default text'],
top: 0,
left: 0,
width: 200
}];
}
});
// Create or update with specific placement
await appElement.addOrUpdateElement(
{
content: 'Positioned content'
},
{
top: 200,
left: 200,
width: 300,
height: 100
}
);
```
</Prop.Extras>
</Prop>
<Prop name="addElement" required type="function" sourceLineNumbers={[660]}> Adds a new app element to the design.
**Parameters**
<Prop.List>
<Prop name="opts" required type="AppElementOptions<A>" sourceLineNumbers={[660]}>
The data and placement of the app element.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="data" required type="A" sourceLineNumbers={[782]}>
The data to attach to the app element.
<Tabs>
<Tab name="Primitive">
A primitive data type that can be used in app element data.
All primitive data types are supported except for symbols and bigints.
</Tab>
<Tab name="ObjectPrimitive">
An object primitive data type that can be used in app element data.
<Tabs />
</Tab>
</Tabs>
</Prop>
<Prop name="placement" type="Placement" sourceLineNumbers={[786]}>
The position, dimensions, and rotation of the app element.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>placement</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`Promise<void>`
<Prop.Extras>
**Examples**
**Add new element with data**
```typescript
import { initAppElement } from "@canva/design";
const appElement = initAppElement<{ content: string; id: string }>({
render: (data) => {
return [{
type: 'text',
children: [data.content || 'Default text'],
top: 0,
left: 0,
width: 200
}];
}
});
// Add a new element
await appElement.addElement({
data: {
content: 'New element content',
id: 'element-' + Date.now()
}
});
```
**Add element with specific placement**
```typescript
import { initAppElement } from "@canva/design";
const appElement = initAppElement<{
title: string;
description: string;
createdAt: number;
}>({
render: (data) => {
return [{
type: 'text',
children: [data.title || 'Default title'],
top: 0,
left: 0,
width: 300,
fontWeight: 'bold',
fontSize: 24
}, {
type: 'text',
children: [data.description || 'Default description'],
top: 50,
left: 0,
width: 300
}];
}
});
// Add element with specific placement
await appElement.addElement({
data: {
title: 'Element Title',
description: 'This is a description of the element',
createdAt: Date.now()
},
placement: {
top: 100,
left: 100,
width: 400,
height: 150,
rotation: 0
}
});
```
</Prop.Extras>
</Prop>
<Prop name="registerOnElementChange" required type="function" sourceLineNumbers={[753]}> A callback that runs when:
* the app element is created
* the app element's data is updated
* the user selects an existing app element
**Parameters**
<Prop.List>
<Prop name="handler" required type="AppElementChangeHandler<A>" sourceLineNumbers={[753]}>
The callback to run when the app element changes.
**Parameters**
<Prop.List>
<Prop name="appElement" required type="object | undefined" sourceLineNumbers={[455]}>
Information about the app element that was changed.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>appElement</strong></>}>
<Prop.List>
<Prop name="data" required type="A" sourceLineNumbers={[459]}>
The app element data in its most recent state.
<Tabs>
<Tab name="Primitive">
A primitive data type that can be used in app element data.
All primitive data types are supported except for symbols and bigints.
</Tab>
<Tab name="ObjectPrimitive">
An object primitive data type that can be used in app element data.
<Tabs />
</Tab>
</Tabs>
</Prop>
<Prop name="version" required type="number" sourceLineNumbers={[463]}>
The version number of the app.
</Prop>
<Prop name="update" required type="function" sourceLineNumbers={[516]}>
Function to update the app element data.
<Prop.Extras>
**Examples**
**Update element data only**
```typescript
if (element) {
await element.update({
data: {
...element.data,
content: 'Updated content',
lastUpdated: Date.now()
}
});
}
```
**Update data and placement**
```typescript
if (element) {
await element.update({
data: {
...element.data,
content: 'Positioned element'
},
placement: {
top: 200,
left: 200,
width: 300,
height: 100
}
});
}
```
**Add metadata to element**
```typescript
if (element) {
await element.update({
data: {
...element.data,
metadata: {
...(element.data.metadata || {}),
lastEdited: Date.now(),
editCount: (element.data.metadata?.editCount || 0) + 1,
},
},
});
}
```
</Prop.Extras>
**Parameters**
<Prop.List>
<Prop name="opts" required type="AppElementOptions<A>" sourceLineNumbers={[516]}>
The data and placement to update the app element with.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="data" required type="A" sourceLineNumbers={[782]}>
The data to attach to the app element.
<Tabs>
<Tab name="Primitive">
A primitive data type that can be used in app element data.
All primitive data types are supported except for symbols and bigints.
</Tab>
<Tab name="ObjectPrimitive">
An object primitive data type that can be used in app element data.
<Tabs />
</Tab>
</Tabs>
</Prop>
<Prop name="placement" type="Placement" sourceLineNumbers={[786]}>
The position, dimensions, and rotation of the app element.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>placement</strong></>}>
<Prop.List>
<Prop name="top" required type="number" sourceLineNumbers={[3846]}>
The distance from the top edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="left" required type="number" sourceLineNumbers={[3855]}>
The distance from the left edge of the container, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `-32768`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="width" required type="number" sourceLineNumbers={[5021]}>
A width, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[5030]}>
A height, in pixels.
* The pixels are relative to their container.
<Prop.Extras>
**Minimum**: `0`
**Maximum**: `32767`
</Prop.Extras>
</Prop>
<Prop name="rotation" type="number" sourceLineNumbers={[3863]}>
A rotation, in degrees.
<Prop.Extras>
**Minimum**: `-180`
**Maximum**: `180`
</Prop.Extras>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`Promise<void>`
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
</Prop.List>
**Returns**
`void`
<Prop.Extras>
**Examples**
**Handle element selection and update**
```typescript
import { initAppElement } from "@canva/design";
const appElement = initAppElement<{ content: string }>({
render: (data) => {
return [{
type: 'text',
children: [data.content || 'Default text'],
top: 0,
left: 0,
width: 200
}];
}
});
// Register a handler for element changes
appElement.registerOnElementChange((element) => {
if (element) {
// Element is created or selected
// Optionally update the element
// element.update({
// data: { ...element.data, lastSelected: Date.now() }
// });
} else {
// No element is selected
}
});
```
**Update element when selected**
```typescript
import { initAppElement } from "@canva/design";
const appElement = initAppElement<{
content: string;
metadata: { created: number; lastSelected: number };
}>({
render: (data) => {
// Render based on data
return [{
type: 'text',
children: [data.content || ''],
top: 0,
left: 0,
width: 200
}];
}
});
// Update element when selected
appElement.registerOnElementChange(async (element) => {
if (element) {
// Check if this is a newly created or a selected element
const isNewElement = !element.data.metadata?.created;
if (isNewElement) {
// Update a new element with initial metadata
await element.update({
data: {
...element.data,
metadata: {
created: Date.now(),
lastSelected: Date.now()
}
}
});
} else {
// Update existing element's last selected time
await element.update({
data: {
...element.data,
metadata: {
...element.data.metadata,
lastSelected: Date.now()
}
}
});
}
}
});
```
</Prop.Extras>
</Prop> </Prop.List>
Open Design
API reference for the openDesign method.
Reads a specified part of the user's design and returns all elements in that part.
Parameters
<Prop.List> <Prop name="options" required type="DesignOpenOptions" sourceLineNumbers={[3690]}> Options for configuring how the design is read.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[1173]}>
The type of context.
The only valid value is `"current_page"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="callback" required type="DesignOpenCallback" sourceLineNumbers={[3690]}> A callback for operating on the design.
**Parameters**
<Prop.List>
<Prop name="session" required type="DesignEditing.CurrentPageSession" sourceLineNumbers={[2633]}>
Session received by the `openDesign` callback.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>session</strong></>}>
<Prop.List>
<Prop name="page" required type="DesignEditing.Page" sourceLineNumbers={[1621]}>
The current page of the design.
<Tabs>
<Tab name="AbsolutePage">
A page with either fixed or unbounded dimensions.
For more information, see [AbsolutePage](/docs/apps/api/latest/design-types-absolute-page/).
</Tab>
<Tab name="Unsupported">
Represents something that's not supported by the Apps SDK.
<Prop.List>
<Prop name="type" required readonly type="string" sourceLineNumbers={[1817]}>
The only valid value is `"unsupported"`.
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
<Prop name="helpers" required type="DesignEditing.PageHelpers" sourceLineNumbers={[1625]}>
These are various utilities that allow apps to do more complex operations on the page.
For more information, see [PageHelpers](/docs/apps/api/latest/design-types-page-helpers/).
</Prop>
<Prop name="sync" required type="function" sourceLineNumbers={[1633]}>
Saves any changes made during the session while keeping the session 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>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`Promise<void>`
</Prop> </Prop.List>
Returns
Promise<void>
Publish Launch
API reference for the publish.launch method.
Launches the design publish with the content publisher intent.
Usage: Launch the content publisher with the same app
typescript
import { publish } from "@canva/design";
import { features } from "@canva/platform";
if (features.isSupported(publish.launch)) {
await publish.launch({ withContentPublisher: 'self' });
}Parameters
<Prop.List> <Prop name="opts" required type="LaunchPublishOpts" sourceLineNumbers={[3901]}> Options for configuring the publish menu.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="withContentPublisher" required type="string" sourceLineNumbers={[3562]}>
The option to make sure the content publisher intent of the current app will be triggered.
The only valid value is `"self"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
Promise<void>
<Prop.Extras>
Throws
unsupported_surface code if not invoked by the design editor intent. </Prop.Extras>
Request Export
API reference for the requestExport method.
Exports the user's design as one or more static files.
Parameters
<Prop.List> <Prop name="request" required type="ExportRequest" sourceLineNumbers={[3909]}> The request object containing configurations of the design export.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>request</strong></>}>
<Prop.List>
<Prop name="acceptedFileTypes" required type="object[]" sourceLineNumbers={[3119]}>
The types of files the user can export their design as.
You must provide at least one file type.
<Tabs>
<Tab name="ExportFileType">
The types of files that Canva supports for exported designs.
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"pdf_standard"`
* `"video"`
* `"gif"`
* `"pptx"`
* `"svg"`
</Prop.Extras>
</Tab>
<Tab name="ExportFileTypeWithProperties">
Object representation of the supported file types with properties where applicable.
<Tabs>
<Tab name="ExportImageFileType">
Supported image file types with properties.
Zip behavior for image file types:
* `auto` (default): Files are zipped together if the design has multiple pages, unzipped if it has one page.
* `always`: Files are always zipped into a single zip file, regardless of page count.
* `never`: Files are never zipped, providing an array of files.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3096]}>
<Prop.Extras>
**Available values**:
* `"png"`
* `"jpg"`
* `"svg"`
</Prop.Extras>
</Prop>
<Prop name="zipped" type="ZipBehavior" sourceLineNumbers={[3097]}>
The behavior of zipping the exported files.
For `png`, `jpg`, and `svg`:
* `auto` (default): Files are zipped together if the design has multiple pages, unzipped if it has one page.
* `always`: Files are always zipped into a single zip file, regardless of page count.
* `never`: Files are never zipped, providing an array of files.
For `video` and `gif`:
* `auto` or `never` (default): Files are never zipped together, regardless of count.
* `always`: Files are always zipped into a single file.
<Prop.Extras>
**Available values**:
* `"auto"`
* `"always"`
* `"never"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="ExportVideoFileType">
Supported video file types with properties.
Zip behavior for video file types:
* `auto` or `never` (default): Files are never zipped together, regardless of count.
* `always`: Files are always zipped into a single file.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3138]}>
<Prop.Extras>
**Available values**:
* `"gif"`
* `"video"`
</Prop.Extras>
</Prop>
<Prop name="zipped" type="ZipBehavior" sourceLineNumbers={[3139]}>
The behavior of zipping the exported files.
For `png`, `jpg`, and `svg`:
* `auto` (default): Files are zipped together if the design has multiple pages, unzipped if it has one page.
* `always`: Files are always zipped into a single zip file, regardless of page count.
* `never`: Files are never zipped, providing an array of files.
For `video` and `gif`:
* `auto` or `never` (default): Files are never zipped together, regardless of count.
* `always`: Files are always zipped into a single file.
<Prop.Extras>
**Available values**:
* `"auto"`
* `"always"`
* `"never"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="ExportPrintFileType">
Supported print file types.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3105]}>
<Prop.Extras>
**Available values**:
* `"pdf_standard"`
* `"pptx"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Tab>
</Tabs>
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
The result of exporting a design. This is a Promise that resolves with the following object:
<Tabs> <Tab name="Completed"> The result when a user successfully completes an export flow.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[3059]}>
The status of the export flow.
The only valid value is `"completed"`.
</Prop>
<Prop name="exportBlobs" required type="ExportBlob[]" sourceLineNumbers={[3070]}>
The exported files.
This array can contain a single link either to a file or a ZIP, or multiple links to individual files.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>exportBlobs</strong></>}>
<Prop.List>
<Prop name="url" required type="string" sourceLineNumbers={[3048]}>
The URL of the exported design.
If a user's design contains multiple pages but is exported in a format that doesn't support multiple pages,
by default this URL will point to a ZIP file that contains each page as a separate file.
If the user has configured the export to not zip the exported files (using the `zipped` property), this URL will point to a single file.
For example:
* If a single-page design is exported as a JPG, the URL will point to a JPG file.
* If a multi-page design is exported as a JPG, the URL will point to a ZIP file that contains a JPG file for each page.
* If a multi-page design is exported as a JPG and the user has set `zipped` to `never` for JPGs, the URL will point to a JPG file and will be one of multiple urls in the exportBlobs array.
* If a multi-page design is exported as a PDF file, the URL will point to a PDF file.
* If a multi-page design is exported as a VIDEO file and the user has set `zipped` to `always` for VIDEOs, the URL will point to a ZIP that contains a VIDEO file.
The following file types support multiple pages:
* `"GIF"`
* `"PDF_STANDARD"`
* `"PPTX"`
* `"VIDEO"`
The following file types do not support multiple pages:
* `"JPG"`
* `"PNG"`
* `"SVG"`
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="title" type="string" sourceLineNumbers={[3063]}>
The title of the design, if set by the user.
</Prop>
</Prop.List>
</Tab>
<Tab name="Aborted"> The result when a user abandons the export flow, such as by closing the export menu.
<Prop.List>
<Prop name="status" required type="string" sourceLineNumbers={[3010]}>
The status of the export flow.
The only valid value is `"aborted"`.
</Prop>
</Prop.List>
</Tab> </Tabs>
Bulk Create Launch
API reference for the bulkCreate.launch method.
Launches the design bulk create with the data connector intent.
Usage: Launch the bulk create panel with the same app
typescript
import { bulkCreate } from "@canva/design";
import { features } from "@canva/platform";
if (features.isSupported(bulkCreate.launch)) {
await bulkCreate.launch({ withDataConnector: 'self' });
}Parameters
<Prop.List> <Prop name="opts" required type="LaunchBulkCreateOpts" sourceLineNumbers={[909]}> Options for configuring the bulk create panel.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="withDataConnector" required type="string" sourceLineNumbers={[3551]}>
The option to make sure the data connector intent of the current app will be triggered.
The only valid value is `"self"`.
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
Promise<void>
<Prop.Extras>
Throws
unsupported_surface code if not invoked by the design editor intent. </Prop.Extras>
Set Page Background
API reference for the setCurrentPageBackground method.
Updates the background of the user's current page. The background can be a solid color, an image or a video.
Usage
Set background color
typescript
import { setCurrentPageBackground } from "@canva/design";
import type { PageBackgroundFill } from "@canva/design";
const background: PageBackgroundFill = {
color: '#F5F5F5',
};
await setCurrentPageBackground(background);Set background image
typescript
import { setCurrentPageBackground } from "@canva/design";
import type { PageBackgroundFill } from "@canva/design";
import type { ImageRef } from "@canva/asset";
const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
const background: PageBackgroundFill = {
asset: {
type: 'image',
ref: exampleImageRef,
altText: { text: 'Background image', decorative: true }
},
};
await setCurrentPageBackground(background);Set background video
typescript
import { setCurrentPageBackground } from "@canva/design";
import type { PageBackgroundFill } from "@canva/design";
import type { VideoRef } from "@canva/asset";
const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;
const background: PageBackgroundFill = {
asset: {
type: 'video',
ref: exampleVideoRef,
altText: { text: 'Background video', decorative: true }
},
};
await setCurrentPageBackground(background);Parameters
<Prop.List> <Prop name="opts" required type="PageBackgroundFill" sourceLineNumbers={[4595]}> The appearance of a page's background.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3187]}>
The color of the fill 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="asset" type="object" sourceLineNumbers={[3191]}>
An image or video to use as the fill.
<Tabs>
<Tab name="Images">
An image asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[3436]}>
The type of fill.
The only valid value is `"image"`.
</Prop>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3440]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[3447]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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="Videos">
A video asset that fills a path's interior.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4968]}>
The type of fill.
The only valid value is `"video"`.
</Prop>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4972]}>
A unique identifier that points to a video asset in Canva's backend.
</Prop>
<Prop name="altText" type="AltText" sourceLineNumbers={[4979]}>
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={[373]}>
The text content.
</Prop>
<Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[381]}>
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.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
Promise<void>
Selection Register on Change
API reference for the selection.registerOnChange method.
Registers a callback that runs when the specified type of content is selected.
- This callback fires immediately if content is already selected when the callback is registered.
- App elements are not supported by this API. For managing selection and updates to app elements, please refer to the
initAppElementAPI call for details and examples.
Usage
Handling plaintext selection
typescript
import { selection } from "@canva/design";
selection.registerOnChange({
scope: 'plaintext',
onChange: async (event) => {
if (event.count > 0) {
const draft = await event.read();
// Do something with the selected text, e.g. `draft.contents[0].text`
}
}
});Handling image selection
typescript
import { selection } from "@canva/design";
selection.registerOnChange({
scope: 'image',
onChange: async (event) => {
if (event.count > 0) {
const draft = await event.read();
// Do something with the selected image ref, e.g. `draft.contents[0].ref`
}
}
});Edit selected image and upload with parentRef
typescript
import { selection } from "@canva/design";
import { getTemporaryUrl, upload } from "@canva/asset";
selection.registerOnChange({
scope: 'image',
onChange: async (event) => {
if (event.count > 0) {
const draft = await event.read();
for (const content of draft.contents) {
// Fetch a temporary URL to the original image
const { url } = await getTemporaryUrl({
type: "image",
ref: content.ref
});
// Apply any edits you want to the image
const processedImageUrl = await applyImageEffect(url);
// Upload the edited image with parentRef
const asset = await upload({
type: "image",
parentRef: content.ref,
url: processedImageUrl,
mimeType: "image/jpeg",
thumbnailUrl: processedImageUrl,
aiDisclosure: "app_generated"
});
// Replace the image ref with the new image ref
content.ref = asset.ref;
}
// Save the changes to the design
await draft.save();
}
}
});Handling video selection
typescript
import { selection } from "@canva/design";
selection.registerOnChange({
scope: 'video',
onChange: async (event) => {
if (event.count > 0) {
const draft = await event.read();
// Do something with the selected video ref, e.g. `draft.contents[0].ref`
}
}
});Handling richtext selection
typescript
import { selection } from "@canva/design";
selection.registerOnChange({
scope: 'richtext',
onChange: async (event) => {
if (event.count > 0) {
const draft = await event.read();
const range = draft.contents[0];
// Do something with the selected richtext, e.g. `range.readPlaintext()`
}
}
});Parameters
<Prop.List> <Prop name="opts" required type="object" sourceLineNumbers={[2858]}> Options for configuring the content selection callback.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="scope" required type="Scope" sourceLineNumbers={[2862]}>
The type of content that triggers a selection change event.
<Prop.Extras>
**Available values**:
* `"plaintext"`
* `"image"`
* `"video"`
* `"richtext"`
</Prop.Extras>
</Prop>
<Prop name="onChange" required type="function" sourceLineNumbers={[2867]}>
The callback to run when the selected content changes.
**Parameters**
<Prop.List>
<Prop name="event" required type="SelectionEvent<Scope>" sourceLineNumbers={[2867]}>
Information about the selection change event.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>event</strong></>}>
<Prop.List>
<Prop name="scope" required readonly type="Scope" sourceLineNumbers={[4393]}>
The type of content that's selected.
<Prop.Extras>
**Available values**:
* `"plaintext"`
* `"image"`
* `"video"`
* `"richtext"`
</Prop.Extras>
</Prop>
<Prop name="count" required readonly type="number" sourceLineNumbers={[4397]}>
The number of selected elements.
</Prop>
<Prop name="read" required type="function" sourceLineNumbers={[4468]}>
Returns a snapshot of the content in the user's selection.
The snapshot is known as the *draft*.
**Returns**
A snapshot of content from a user's design. This is a `Promise` that resolves with the following object:
<Prop.List>
<Prop name="contents" required readonly type="SelectionValue<Scope>[]" sourceLineNumbers={[991]}>
The individual content items that exist within the snapshot.
Any changes made to this array won't be reflected in the user's design until the `save` method is called.
<Tabs>
<Tab name="plaintext">
<Prop.List>
<Prop name="text" required type="string" sourceLineNumbers={[4514]}>
The text content.
</Prop>
</Prop.List>
</Tab>
<Tab name="image">
<Prop.List>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[4523]}>
A unique identifier that points to an image asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="video">
<Prop.List>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4532]}>
A unique identifier that points to an video asset in Canva's backend.
</Prop>
</Prop.List>
</Tab>
<Tab name="richtext">
Provides methods for interacting with a range of formatted text.
<Prop.List>
<Prop name="formatParagraph" required type="function" sourceLineNumbers={[4160]}>
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={[4160]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[4160]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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={[4202]}>
Formats a region of text with inline formatting properties.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4202]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[4202]}>
The formatting to apply to the text.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4240]}>
Appends the specified characters to the end of the range.
**Parameters**
<Prop.List>
<Prop name="characters" required type="string" sourceLineNumbers={[4240]}>
The characters to append to the richtext range.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4240]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4241]}>
A segment of a richtext range.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
<Prop.List>
<Prop name="index" required type="number" sourceLineNumbers={[865]}>
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={[869]}>
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={[4286]}>
Replaces a region of text with the specified characters.
**Parameters**
<Prop.List>
<Prop name="bounds" required type="Bounds" sourceLineNumbers={[4286]}>
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={[865]}>
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={[869]}>
The number of characters in the segment, starting from the index.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="characters" required type="string" sourceLineNumbers={[4286]}>
The replacement characters.
</Prop>
<Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[4286]}>
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={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
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={[4290]}>
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={[865]}>
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={[869]}>
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={[4329]}>
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={[4376]}>
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={[4840]}>
The plaintext content of the region.
</Prop>
<Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[4844]}>
The formatting of the region.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
<Prop.List>
<Prop name="color" type="string" sourceLineNumbers={[3512]}>
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={[3521]}>
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={[3526]}>
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={[3531]}>
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={[3536]}>
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={[3540]}>
An external URL that the text links to.
</Prop>
<Prop name="fontRef" type="FontRef" sourceLineNumbers={[4078]}>
A unique identifier that points to a font asset in Canva's backend.
</Prop>
<Prop name="fontSize" type="number" sourceLineNumbers={[4087]}>
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={[4092]}>
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={[4096]}>
The list indentation level of the paragraph.
</Prop>
<Prop name="listMarker" type="string" sourceLineNumbers={[4105]}>
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>
</Tab>
</Tabs>
</Prop>
<Prop name="save" required type="function" sourceLineNumbers={[1051]}>
Saves changes made to the content items in the `contents` array.
Once this method is called:
* Any changes the app has made to to the content will be reflected in the user's design.
* Any changes the user has made to the content since the snapshot was created may be overwritten.
* Only properties that are different from the original state will be written to the design.
**Returns**
`Promise<void>`
<Prop.Extras>
**Examples**
**Save changes to selected text**
```typescript
import { selection } from "@canva/design";
selection.registerOnChange({
scope: 'plaintext',
onChange: async (event) => {
if (event.count > 0) {
const draft = await event.read();
// Make changes to the content
for (const content of draft.contents) {
content.text = content.text.toUpperCase();
}
// Save the changes to the design
await draft.save();
}
}
});
```
**Modify then save rich text content**
```typescript
import { selection } from "@canva/design";
selection.registerOnChange({
scope: 'richtext',
onChange: async (event) => {
if (event.count > 0) {
const draft = await event.read();
const range = draft.contents[0];
// Get the plain text
const text = range.readPlaintext();
// Apply formatting to the entire text
range.formatText(
{ index: 0, length: text.length },
{ fontWeight: 'bold', color: '#0066CC' }
);
// Save the formatted text back to the design
await draft.save();
}
}
});
```
</Prop.Extras>
</Prop>
</Prop.List>
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
() => void
Overlay Register on Can Open
API reference for the overlay.registerOnCanOpen method.
Registers a callback that runs when the canOpen state of an overlay target changes.
Usage
Register overlay handler
typescript
import { overlay } from "@canva/design";
overlay.registerOnCanOpen({
target: 'image_selection',
onCanOpen: async (event) => {
if (event.canOpen) {
// Can open overlay for selected image
}
}
});Open image editing overlay
typescript
import { overlay } from "@canva/design";
overlay.registerOnCanOpen({
target: 'image_selection',
onCanOpen: async (event) => {
if (event.canOpen) {
const processId = await event.open({
launchParameters: {
mode: 'edit'
}
});
// Overlay process started, with `processId`
}
}
});Open overlay with filters
typescript
import { overlay } from "@canva/design";
overlay.registerOnCanOpen({
target: 'image_selection',
onCanOpen: async (event) => {
if (event.canOpen) {
await event.open({
launchParameters: {
mode: 'edit',
filters: ['brightness', 'contrast', 'saturation']
}
});
}
}
});Handle overlay unavailability
typescript
import { overlay } from "@canva/design";
overlay.registerOnCanOpen({
target: 'image_selection',
onCanOpen: async (event) => {
if (!event.canOpen) {
// Cannot open overlay, handle specific reasons
switch (event.reason) {
case 'no_selection':
// No image is selected
break;
case 'invalid_selection':
// Selected content cannot be edited
break;
}
}
}
});Parameters
<Prop.List> <Prop name="opts" required type="object" sourceLineNumbers={[2724]}> Options for configuring the callback.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>opts</strong></>}>
<Prop.List>
<Prop name="target" required type="Target" sourceLineNumbers={[2728]}>
The target to check the `canOpen` state of.
The only valid value is `"image_selection"`.
</Prop>
<Prop name="onCanOpen" required type="function" sourceLineNumbers={[2737]}>
A callback that runs when the `canOpen` state of the specified target changes.
This callback fires immediately.
**Parameters**
<Prop.List>
<Prop name="event" required type="OverlayOpenableEvent<Target>" sourceLineNumbers={[2737]}>
Information about whether or not an overlay can be opened for the specified target.
<Tabs>
<Tab name="OverlayUnopenableEvent">
Information about an overlay that can't be opened for the specified target.
<Prop.List>
<Prop name="canOpen" required type="boolean" sourceLineNumbers={[3741]}>
Indicates that the overlay can't be opened for the specified target.
The only valid value is `false`.
</Prop>
<Prop name="reason" required type="string" sourceLineNumbers={[3745]}>
Indicates the reason the overlay can't be opened for the specified target.
</Prop>
</Prop.List>
</Tab>
<Tab name="object">
<Prop.List>
<Prop name="canOpen" required type="boolean" sourceLineNumbers={[3710]}>
Indicates that the overlay can be opened for the selected image.
The only valid value is `true`.
</Prop>
<Prop name="open" required readonly type="function" sourceLineNumbers={[3715]}>
Opens an overlay for the selected image.
**Parameters**
<Prop.List>
<Prop name="options" required type="object" sourceLineNumbers={[3715]}>
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>options</strong></>}>
<Prop.List>
<Prop name="launchParameters" type="unknown" sourceLineNumbers={[3722]}>
Parameters to pass to the overlay when it opens.
This can be any type of structured data.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
**Returns**
A unique identifier that references an app runtime process.
`Promise<AppProcessId>`
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop>
</Prop.List>
**Returns**
`void`
</Prop>
</Prop.List>
</PillAccordion>
</Prop> </Prop.List>
Returns
() => void
UI Start Drag
API reference for the ui.startDrag method.
WARNING: This API is deprecated, and is no longer recommended for use, and should be removed from your app.
The method has been superseded by startDragToPoint.
Adds the specified element or content to a design at the end of a drag event.
Parameters
<Prop.List> <Prop name="event" required type="DragStartEvent<E>" sourceLineNumbers={[4860]}> A drag start event.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>event</strong></>}>
<Prop.List />
</PillAccordion>
</Prop>
<Prop name="dragData" required type="object" sourceLineNumbers={[4860]}> Element or content to be added to the design at the end of the drag event.
<Tabs>
<Tab name="Audio">
Audio track to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[818]}>
The type of element.
The only valid value is `"audio"`.
</Prop>
<Prop name="resolveAudioRef" required type="function" sourceLineNumbers={[822]}>
A function that returns a reference (ref) to an audio asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="AudioRef" sourceLineNumbers={[823]}>
A unique identifier that references an audio asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="durationMs" required type="number" sourceLineNumbers={[828]}>
The duration of the audio track, in milliseconds.
</Prop>
<Prop name="title" required type="string" sourceLineNumbers={[832]}>
A human readable title for the audio track.
</Prop>
</Prop.List>
</Tab>
<Tab name="Embeds">
Embed element to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2960]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[2964]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[2968]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="embedUrl" required type="string" sourceLineNumbers={[2975]}>
The URL of media that can be embedded, such as the URL of a YouTube video.
This URL must be supported by the Iframely API.
</Prop>
</Prop.List>
</Tab>
<Tab name="Text">
Text element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4780]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" type="string[]" sourceLineNumbers={[4784]}>
The text content to drag.
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4789]}>
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="fontWeight" type="FontWeight" sourceLineNumbers={[4794]}>
The weight (thickness) of 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={[4799]}>
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={[4804]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
Video element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4901]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="resolveVideoRef" required type="function" sourceLineNumbers={[4905]}>
A function that returns a reference (ref) to a video asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4906]}>
A unique identifier that references a video asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[4911]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[4923]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="fullSize" type="Dimensions" sourceLineNumbers={[4919]}>
The dimensions of the full-size video.
* These dimensions are used when adding the video to the design
* If omitted, the `previewSize` dimensions are used as a fallback.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fullSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="Images">
Image element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[973]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[977]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="resolveImageRef" required type="function" sourceLineNumbers={[3153]}>
A function that returns a reference (ref) to an audio asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3154]}>
A unique identifier that references an image asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[3159]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="fullSize" type="Dimensions" sourceLineNumbers={[3163]}>
The dimensions of the full-size image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fullSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
Promise<void>
UI Start Drag to Cursor
API reference for the ui.startDragToCursor method.
Adds the specified element or content to responsive documents, which slot things into a text stream at the end of a drag event.
Parameters
<Prop.List> <Prop name="event" required type="DragStartEvent<E>" sourceLineNumbers={[4876]}> A drag start event.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>event</strong></>}>
<Prop.List />
</PillAccordion>
</Prop>
<Prop name="dragData" required type="object" sourceLineNumbers={[4876]}> Element or content to be added to the design at the end of the drag event.
<Tabs>
<Tab name="Embeds">
Embed element to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2960]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[2964]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[2968]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="embedUrl" required type="string" sourceLineNumbers={[2975]}>
The URL of media that can be embedded, such as the URL of a YouTube video.
This URL must be supported by the Iframely API.
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
Video element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4901]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="resolveVideoRef" required type="function" sourceLineNumbers={[4905]}>
A function that returns a reference (ref) to a video asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4906]}>
A unique identifier that references a video asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[4911]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[4923]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="fullSize" type="Dimensions" sourceLineNumbers={[4919]}>
The dimensions of the full-size video.
* These dimensions are used when adding the video to the design
* If omitted, the `previewSize` dimensions are used as a fallback.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fullSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="Images">
Image element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[973]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[977]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="resolveImageRef" required type="function" sourceLineNumbers={[3153]}>
A function that returns a reference (ref) to an audio asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3154]}>
A unique identifier that references an image asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[3159]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="fullSize" type="Dimensions" sourceLineNumbers={[3163]}>
The dimensions of the full-size image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fullSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
Promise<void>
UI Start Drag to Point
API reference for the ui.startDragToPoint method.
Adds the specified element or content to fixed designs, which use a coordinate-based positioning system at the end of a drag event.
Parameters
<Prop.List> <Prop name="event" required type="DragStartEvent<E>" sourceLineNumbers={[4868]}> A drag start event.
<PillAccordion defaultExpanded={true} title={<>Properties of <strong>event</strong></>}>
<Prop.List />
</PillAccordion>
</Prop>
<Prop name="dragData" required type="object" sourceLineNumbers={[4868]}> Element or content to be added to the design at the end of the drag event.
<Tabs>
<Tab name="Audio">
Audio track to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[818]}>
The type of element.
The only valid value is `"audio"`.
</Prop>
<Prop name="resolveAudioRef" required type="function" sourceLineNumbers={[822]}>
A function that returns a reference (ref) to an audio asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="AudioRef" sourceLineNumbers={[823]}>
A unique identifier that references an audio asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="durationMs" required type="number" sourceLineNumbers={[828]}>
The duration of the audio track, in milliseconds.
</Prop>
<Prop name="title" required type="string" sourceLineNumbers={[832]}>
A human readable title for the audio track.
</Prop>
</Prop.List>
</Tab>
<Tab name="Embeds">
Embed element to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[2960]}>
The type of element.
The only valid value is `"embed"`.
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[2964]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[2968]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="embedUrl" required type="string" sourceLineNumbers={[2975]}>
The URL of media that can be embedded, such as the URL of a YouTube video.
This URL must be supported by the Iframely API.
</Prop>
</Prop.List>
</Tab>
<Tab name="Text">
Text element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4780]}>
The type of element.
The only valid value is `"text"`.
</Prop>
<Prop name="children" type="string[]" sourceLineNumbers={[4784]}>
The text content to drag.
</Prop>
<Prop name="textAlign" type="string" sourceLineNumbers={[4789]}>
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="fontWeight" type="FontWeight" sourceLineNumbers={[4794]}>
The weight (thickness) of 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={[4799]}>
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={[4804]}>
The decoration of the font.
<Prop.Extras>
**Default value**: `"none"`
</Prop.Extras>
<Prop.Extras>
**Available values**:
* `"none"`
* `"underline"`
</Prop.Extras>
</Prop>
</Prop.List>
</Tab>
<Tab name="Videos">
Video element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[4901]}>
The type of element.
The only valid value is `"video"`.
</Prop>
<Prop name="resolveVideoRef" required type="function" sourceLineNumbers={[4905]}>
A function that returns a reference (ref) to a video asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="VideoRef" sourceLineNumbers={[4906]}>
A unique identifier that references a video asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[4911]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[4923]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="fullSize" type="Dimensions" sourceLineNumbers={[4919]}>
The dimensions of the full-size video.
* These dimensions are used when adding the video to the design
* If omitted, the `previewSize` dimensions are used as a fallback.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fullSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
<Tab name="Images">
Image element or content to be added to the design at the end of a drag event.
<Prop.List>
<Prop name="type" required type="string" sourceLineNumbers={[973]}>
The type of element.
The only valid value is `"image"`.
</Prop>
<Prop name="previewSize" required type="Dimensions" sourceLineNumbers={[977]}>
The dimensions of the preview image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>previewSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
<Prop name="resolveImageRef" required type="function" sourceLineNumbers={[3153]}>
A function that returns a reference (ref) to an audio asset in Canva's backend.
**Returns**
A `Promise` that resolves with the following object:
<Prop.List>
<Prop name="ref" required type="ImageRef" sourceLineNumbers={[3154]}>
A unique identifier that references an image asset in Canva's backend.
</Prop>
</Prop.List>
</Prop>
<Prop name="previewUrl" required type="string" sourceLineNumbers={[3159]}>
The URL of an image to display under the user's cursor during the drag and drop event.
</Prop>
<Prop name="fullSize" type="Dimensions" sourceLineNumbers={[3163]}>
The dimensions of the full-size image.
<PillAccordion defaultExpanded={false} title={<>Properties of <strong>fullSize</strong></>}>
<Prop.List>
<Prop name="width" required type="number" sourceLineNumbers={[2887]}>
A width, in pixels.
</Prop>
<Prop name="height" required type="number" sourceLineNumbers={[2891]}>
A height, in pixels.
</Prop>
</Prop.List>
</PillAccordion>
</Prop>
</Prop.List>
</Tab>
</Tabs>
</Prop> </Prop.List>
Returns
Promise<void>
Design API Changelog
The latest changes for the Canva Apps SDK @canva/design package.
2.8.0 - 2026-02-02
Added
- Added a CHANGELOG.md to track changes.
- This introduces 2 new APIs, bulkCreate and publish, each with a corresponding launch function that allows the app to launch these experiences directly using the app's set up Data Connector and Content Publisher intents.
Fixed
- Improve
mailtoURI validation to more accurately detect valid email addresses.
Other
- Updated types for
requestExportinto separate named objects
2.7.5 - 2025-12-09
Added
- Added support for custom dimensions in the
addPageAPI call. - Added the ability to configure the zipped behaviour of certain types when exporting with
requestExport.
2.7.4 - 2025-11-28
Added
- Added
design.getDesignMetadatamethod, which allows apps to get information about the design. See the documentation.
2.7.3 - 2025-10-13
Deprecated
- Deprecated
CurrentPageResultin favour ofCurrentPageSession.
Removed
- We no longer provide
indexparameter in theforEachcallbacks.
2.7.2 - 2025-08-05
Deprecated
- Deprecate
design.getDefaultPageDimensions, usedesign.getDesignMetadatainstead. See the documentation.
2.7.0 - 2025-07-15
Added
- Added the
getDesignMetadatamethod, which allows apps to get information about the design. See the documentation.
Deprecated
- Deprecated
design.getDefaultPageDimensions, usedesign.getDesignMetadatainstead. See the documentation.
2.6.1 - 2025-06-24
Added
openDesign: Added new async helper methodsgroupandungroup. See the documentation on PageHelpers.
Changed
openDesign: Design Editing API is out of preview and Generally Available.- Breaking:
openDesignfunction signature changes:saveis superseded bysync. Unlikesave,synccan be called multiple times as needed.- Renamed page type:
fixed→absolute. - New page type:
unsupported, which represents pages that are notabsolute. - Renamed
elementBuildertoelementStateBuilder. - Removed
cloneElement. mediaandcolorfills are superseded bymediaContainerandcolorContainer.- For shape path fills,
isMediaEditableintroduced to indicate editability.
2.4.0 - 2025-02-17
Added
- Latest version of the App Element API is out of preview and Generally Available. This version enables atomic and predictable operations that are no longer tied current selection. To learn more, see App Elements.
2.3.0 - 2024-12-15
Added
- Content Query API is out of preview and Generally Available.
- Introduced a test harness to allow for unit testing of the package.
2.2.1 - 2024-10-21
Added
- Updated App Element API to enable atomic and predictable operations that are no longer tied current selection. To learn more, see App Elements documentation.
2.1.0 - 2024-09-23
Deprecated
- Deprecated
NativeElementTypetype.
2.0.0 - 2024-09-20
Changed
- Breaking: See Apps SDK Migration Guide for full list of changes.
1.10.0 - 2024-08-22
Added
- Added
altTextproperty to image elements. - Added design.overlay.registerOnCanOpen which was previously in beta.
1.9.0 - 2024-05-29
Added
- Added the ability to read/write video via the Selection API.
1.8.0 - 2024-05-06
Added
- NativeVideoElement is now supported in app elements. See the documentation.
1.7.0 - 2024-04-10
Added
- Added design.getDesignToken which was previously in beta. See the documentation.
1.6.0 - 2024-02-25
1.5.0 - 2024-02-12
Changed
- Updated
fontWeightofstartDragto allow more values. - Exported some additional types, such as
FontWeightandTextAttributes.
1.4.0 - 2023-12-13
Removed
- Removed video elements from
AppElementRendererOutput.
Fixed
- Excluded
undefinedinArraytype, and removedbigint,Set, andMaptypes fromAppElementDatato align with existing internal validation.
1.3.0 - 2023-12-12
Added
- Initial NPM release of
@canva/designpackage.