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();
Parameters
This method doesn't have any parameters.
Returns
An object with the following properties:
Appends characters to the end of a richtext range.
Example
import { createRichtextRange } from "@canva/preview/design";const range = createRichtextRange();range.appendText("Hello world");
Parameters
The text to append to the range.
The inline formatting options for the text.
Returns
An object with the following properties:
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" });
Parameters
A region of text.
The index of the character that marks the start of the region.
The length of the region.
The paragraph formatting options for the text.
Returns
An object with the following properties:
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" });
Parameters
A region of text.
The index of the character that marks the start of the region.
The length of the region.
The inline formatting options for the text.
Returns
An object with the following properties:
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"
Returns
A Promise
that resolves with a string.
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" }]
Returns
An array of text regions.
Each region is a object with the following properties:
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");
Parameters
A region of text.
The index of the character that marks the start of the region.
The length of the region.
The replacement text.
The inline formatting options for the text.
Returns
An object with the following properties:
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.
A unique identifier that references a font in Canva's backend. To learn more, see Fonts.
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
.
The indentation level of a list item.
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"
.
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.
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"
.
The weight of the font.
The available options include:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
The default value is "normal"
.
The style of the font.
The available options include:
"normal"
"italic"
The default value is "normal"
.
The decoration of the font.
The available options include:
"none"
"underline"
The default value is "none"
.
The strikethrough styling of the text.
The available options include:
"none"
"strikethrough"
The default value is "none"
.
The URL of a web page to use as a link for the text.