selection.registerOnChange
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.
Usage
Handling plaintext selection
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
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`}}});
Handling video selection
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
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
opts
object
Options for configuring the content selection callback.
scope
Scope
The type of content that triggers a selection change event.
Available values:
"plaintext"
"image"
"video"
"richtext"
onChange
function
The callback to run when the selected content changes.
Parameters
event
SelectionEvent<Scope>
Information about the selection change event.
scope
Scope
Read-onlyThe type of content that's selected.
Available values:
"plaintext"
"image"
"video"
"richtext"
count
number
Read-onlyThe number of selected elements.
read
function
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:
contents
SelectionValue<Scope>[]
Read-onlyThe 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.
text
string
The text content.
ref
ImageRef
A unique identifier that points to an image asset in Canva's backend.
ref
VideoRef
A unique identifier that points to an video asset in Canva's backend.
Provides methods for interacting with a range of formatted text.
formatParagraph
function
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
bounds
Bounds
The segment of the range on which to apply the formatting.
index
number
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
The number of characters in the segment, starting from the index.
formatting
RichtextFormatting
The formatting to apply to the paragraph(s).
color
string
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
The weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
fontStyle
string
The style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
The decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
The strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
An external URL that the text links to.
fontRef
FontRef
A unique identifier that points to a font asset in Canva's backend.
fontSize
number
The size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
Minimum: 1
Maximum: 100
textAlign
string
The alignment of the text.
Default value: "start"
Available values:
"start"
"center"
"end"
"justify"
listLevel
number
The list indentation level of the paragraph.
listMarker
string
The appearance of list item markers.
This property only has an effect if listLevel
is greater than 0.
Default value: "none"
Available values:
"none"
"disc"
"circle"
"square"
"decimal"
"lower-alpha"
"lower-roman"
"checked"
"unchecked"
Returns
void
Examples
Format paragraph as a heading
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Heading Text\nRegular paragraph text.");// Format just the first paragraph as a headingrange.formatParagraph({ index: 0, length: 12 }, // Only need to include part of the paragraph{fontSize: 24,fontWeight: 'bold',textAlign: 'center'});
Create a bulleted list
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 listrange.formatParagraph({ index: 0, length: text.length },{listLevel: 1,listMarker: 'disc'});
formatText
function
Formats a region of text with inline formatting properties.
Parameters
bounds
Bounds
The segment of the range on which to apply the formatting.
index
number
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
The number of characters in the segment, starting from the index.
formatting
InlineFormatting
The formatting to apply to the text.
color
string
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
The weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
fontStyle
string
The style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
The decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
The strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
An external URL that the text links to.
Returns
void
Examples
Format specific words in a paragraph
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
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'});
appendText
function
Appends the specified characters to the end of the range.
Parameters
characters
string
The characters to append to the richtext range.
formatting
InlineFormatting
Optional formatting to apply to the appended text.
color
string
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
The weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
fontStyle
string
The style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
The decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
The strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
An external URL that the text links to.
Returns
bounds
Bounds
A segment of a richtext range.
index
number
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
The number of characters in the segment, starting from the index.
Examples
Append plain text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("First paragraph. ");// Append more text to the existing contentconst 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
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Normal text followed by ");// Append formatted textrange.appendText("bold red text", {fontWeight: 'bold',color: '#FF0000'});// Append a new paragraphrange.appendText("\nThis is a new paragraph.");
replaceText
function
Replaces a region of text with the specified characters.
Parameters
bounds
Bounds
The segment of the range to replace.
index
number
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
The number of characters in the segment, starting from the index.
characters
string
The replacement characters.
formatting
InlineFormatting
The formatting to apply to the replaced text.
color
string
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
The weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
fontStyle
string
The style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
The decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
The strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
An external URL that the text links to.
Returns
bounds
Bounds
The bounds of the replacement characters within the updated range.
index
number
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
The number of characters in the segment, starting from the index.
Examples
Replace text while maintaining some formatting
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
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Regular text that needs emphasis.");// Replace "needs emphasis" with formatted textrange.replaceText({ index: 17, length: 15 },"is important",{fontWeight: 'bold',fontStyle: 'italic',color: '#0066CC'});
readPlaintext
function
Returns the current state of the richtext as plaintext.
Returns
string
Examples
Extract plain text content
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 formattingconst plainText = range.readPlaintext();// Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting."
Search within text content
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text contains a searchable term.");// Search for a specific wordconst plainText = range.readPlaintext();const searchTerm = "searchable";const index = plainText.indexOf(searchTerm);if (index !== -1) {// Format the found termrange.formatText({ index, length: searchTerm.length },{ fontWeight: 'bold', decoration: 'underline' });}
readTextRegions
function
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
text
string
The plaintext content of the region.
formatting
Partial<RichtextFormatting>
The formatting of the region.
color
string
The color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
The weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
fontStyle
string
The style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
The decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
The strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
An external URL that the text links to.
fontRef
FontRef
A unique identifier that points to a font asset in Canva's backend.
fontSize
number
The size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
Minimum: 1
Maximum: 100
textAlign
string
The alignment of the text.
Default value: "start"
Available values:
"start"
"center"
"end"
"justify"
listLevel
number
The list indentation level of the paragraph.
listMarker
string
The appearance of list item markers.
This property only has an effect if listLevel
is greater than 0.
Default value: "none"
Available values:
"none"
"disc"
"circle"
"square"
"decimal"
"lower-alpha"
"lower-roman"
"checked"
"unchecked"
Examples
Get text with formatting information
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 regionsconst 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
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Mixed ", {});range.appendText("formatted ", { fontWeight: 'bold' });range.appendText("text", { color: '#0066CC' });// Analyze formatting variationsconst regions = range.readTextRegions();const formattingTypes = regions.map(region => {const formatting = region.formatting || {};return {text: region.text,hasWeight: !!formatting.fontWeight,hasColor: !!formatting.color};});
save
function
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>
Examples
Save changes to selected text
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 contentfor (const content of draft.contents) {content.text = content.text.toUpperCase();}// Save the changes to the designawait draft.save();}}});
Modify then save rich text content
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 textconst text = range.readPlaintext();// Apply formatting to the entire textrange.formatText({ index: 0, length: text.length },{ fontWeight: 'bold', color: '#0066CC' });// Save the formatted text back to the designawait draft.save();}}});
Returns
void
Returns
() => void