createRichtextRange

API reference for the createRichtextRange method.

Creates a richtext range, which is an object that represents a range of formatted text — anything from a single word to multiple paragraphs — and exposes methods for safely interacting with that text.

To learn more, see Creating text.

Usage

import { createRichtextRange } from "@canva/preview/design";
const range = createRichtextRange();

tsx

Parameters

This method doesn't have any parameters.

Returns

An object with the following properties:

#appendTextfunction

Required

Appends characters to the end of a richtext range.

Example

import { createRichtextRange } from "@canva/preview/design";
const range = createRichtextRange();
range.appendText("Hello world");

tsx

Parameters

#charactersstring

Required

The text to append to the range.

#formattingobject

Optional

The inline formatting options for the text.

Returns

An object with the following properties:

#boundsobject

Required

A region of text.

#bounds.startnumber

Required

The index of the character that marks the start of the region.

#bounds.lengthnumber

Required

The length of the region.

#formatParagraphfunction

Required

Formats all paragraphs that overlap the given bounds. The newline character — \n — indicates the end of a paragraph. All paragraphs that overlap the provided bounds will be formatted in their entirety.

Example

import { createRichtextRange } from "@canva/preview/design";
const range = createRichtextRange();
range.appendText("This is the first paragraph.\nThis is the second paragraph.");
range.formatParagraph({ start: 0, length: 1 }, { fontWeight: "bold" });

tsx

Parameters

#boundsobject

Required

A region of text.

#bounds.startnumber

Required

The index of the character that marks the start of the region.

#bounds.lengthnumber

Required

The length of the region.

#formattingobject

Required

The paragraph formatting options for the text.

Returns

An object with the following properties:

#boundsobject

Required

The boundaries of the formatted text.

#bounds.startnumber

Required

The index of the character that marks the start of the formatted text.

#bounds.lengthnumber

Required

The length of the formatted text.

#formatTextfunction

Required

Formats the specified region of text with inline formatting.

Example

import { createRichtextRange } from "@canva/preview/design";
const range = createRichtextRange();
range.appendText("Hello world");
range.formatText({ start: 0, length: 5 }, { fontWeight: "bold" });

tsx

Parameters

#boundsobject

Required

A region of text.

#bounds.startnumber

Required

The index of the character that marks the start of the region.

#bounds.lengthnumber

Required

The length of the region.

#formattingobject

Required

The inline formatting options for the text.

Returns

An object with the following properties:

#boundsobject

Required

A region of text.

#bounds.startnumber

Required

The index of the character that marks the start of the region.

#bounds.lengthnumber

Required

The length of the region.

#readPlaintextfunction

Required

Gets the plaintext representation of a richtext range.

Example

import { createRichtextRange } from "@canva/preview/design";
const range = createRichtextRange();
range.appendText("Hello world");
const plaintext = range.readPlaintext(); // => "Hello world"

tsx

Returns

A Promise that resolves with a string.

#readTextRegionsfunction

Required

Gets the current state of the richtext range as an array of text regions.

Example

import { createRichtextRange } from "@canva/preview/design";
const range = createRichtextRange();
range.appendText("Hello world");
const regions = range.readTextRegions();
console.log(regions); // => [{ text: "Hello world" }]

tsx

Returns

An array of text regions.

Each region is a object with the following properties:

#textstring

Required

The plaintext content of the region.

#formattingobject

Required

The formatting information for the region.

#replaceTextfunction

Required

Replaces a region of richtext with the specified characters.

Example

import { createRichtextRange } from "@canva/preview/design";
const range = createRichtextRange();
range.appendText("Hello world");
range.replaceText({ start: 0, index: 5 }, "HELLO");

tsx

Parameters

#boundsobject

Required

A region of text.

#bounds.startnumber

Required

The index of the character that marks the start of the region.

#bounds.lengthnumber

Required

The length of the region.

#charactersstring

Required

The replacement text.

#formattingobject

Optional

The inline formatting options for the text.

Returns

An object with the following properties:

#boundsobject

Required

A region of text.

#bounds.startnumber

Required

The index of the character that marks the start of the region.

#bounds.lengthnumber

Required

The length of the region.

Formatting options

Richtext can be formatted in a variety of ways.

The formatting options fall into the following categories:

Paragraph formatting
Inline formatting

The available options depend on how the text is being operated on.

Paragraph formatting

Apps can only use paragraph formatting when operating on entire paragraphs.

#fontRefstring

Optional

A unique identifier that references a font in Canva's backend. To learn more, see Fonts.

#fontSizenumber

Optional

The size of the text, in pixels. This must be an integer between 1 and 1000 (inclusive).

In the user interface, the font size is displayed as points (pts), not pixels. This means the font size defined here will be different from what's shown to the user.

The default value is 16.

#listLevelstring

Optional

The indentation level of a list item.

#listMarkerstring

Optional

The appearance of a list item.

The available options include:

"none"
"disc"
"circle"
"square"
"decimal"
"lower-alpha"
"lower-roman"
"checked"
"unchecked"

The default value is "none".

#textAlignstring

Optional

The alignment of the text.

The available options include:

"start"
"center"
"end"

The default value is "start".

Inline formatting

Apps can use inline formatting when operating on all text, including paragraphs.

#colorstring

Optional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol — for example, "#ff0099".

The default value is "#000000".

#fontWeightstring

Optional

The weight of the font.

The available options include:

"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"

The default value is "normal".

#fontStylestring

Optional

The style of the font.

The available options include:

"normal"
"italic"

The default value is "normal".

#decorationstring

Optional

The decoration of the font.

The available options include:

"none"
"underline"

The default value is "none".

#strikethroughstring

Optional

The strikethrough styling of the text.

The available options include:

"none"
"strikethrough"

The default value is "none".

#linkstring

Optional

The URL of a web page to use as a link for the text.