selection.registerOnChange

API reference for the selection.registerOnChange method.

Registers a callback that runs when a user selects (or deselects) content within a design.

To learn more, see:

import { selection } from "@canva/design";
await selection.registerOnChange({
scope: "plaintext",
onChange: (event) => {
console.log(event);
},
});
ts

Before an app that uses this method can be submitted for review, the following permissions must be enabled via the Developer Portal:

  • canva:design:content:read, if the app calls the read method
  • canva:design:content:write, if the app calls the save method

To learn more, see Configuring permissions.

#optionsobject
Required

The options for registering a selection callback.

#options.scopestring
Required

The type of content that should trigger a selection event.

The available options include:

  • "image"
  • "plaintext"
  • "richtext"
  • "video"
#options.onChangefunction
Required

The callback that runs when a user selects or deselects the specified type of content.

#options.onChange(event)object
Required

The selection event.

#options.onChange(event.scope)string
Required

The type of content that's selected. This matches the value passed into the scope property.

#options.onChange(event.count)number
Required

The number of distinct pieces of content that are selected.

#options.onChange(event.read())function
Required

Reads the selected content.

Returns

A Promise that resolves with the selected content and a save method for persisting changes to the content.

#options.onChange(event.read().contents)array
Required

The selected content. Each distinct piece of content — for example, the content of two separate text elements — is a separate object. These objects have properties and methods for interacting with the content.

The available properties depend on the value of the scope property.

Images

If the scope is "image", each object has the following properties:

#refstring
Required

An identifier that points to an image asset in Canva's backend.

Plain text

If the scope is "plaintext", each object has the following properties:

#textstring
Required

The text content, as plain text.

Rich text

If the scope is "richtext", each object has the following properties:

#appendTextfunction
Required

Appends the provided text to the selected text content.

Parameters

#charactersstring
Required

The text to append to the selected text content.

#formattingobject
Optional

The formatting of the text. To learn more, see Rich text formatting.

Example: Appending text

for (const content of draft.contents) {
content.appendText("This text was appended.");
}
ts
#formatTextfunction
Required

Formats the specified range of text.

Parameters

#boundsobject
Required

The range of text to format.

#bounds.indexnumber
Required

The index of a character within the text content from which to start formatting the text. For example, a value of 0 will format the text from the beginning of the text.

#bounds.lengthnumber
Required

The length of the text region to format.

#formattingobject
Required

The formatting to apply to the text. To see the available options, see Rich text formatting.

Example: Making text bold

for (const content of draft.contents) {
const regions = await content.readTextRegions();
for (const region of regions) {
content.formatText(
{ index: 0, length: region.text.length },
{ fontWeight: "bold" }
);
}
}
ts
#readPlaintextfunction
Required

Gets the selected text content as plain text — that is, the text without formatting information.

Returns

A Promise that resolves with the plain text of the selected text.

Example: Reading rich text as plain text

for (const content of draft.contents) {
await content.readPlaintext(); // => "Hello world."
}
ts
#readTextRegionsfunction
Required

Gets the selected text content as rich text — that is, the text with formatting information.

Returns

A Promise that resolves with an array of "region" objects that represent regions of formatted text:

#regionobject
Required

A region of text. A separate region is created every time the formatting of the text changes.

#region.textstring
Required

The plain text content of the region.

#region.formattingobject
Optional

The formatting of the text content. To learn more, see Rich text formatting.

Example: Reading text regions

for (const content of draft.contents) {
const regions = await content.readTextRegions();
console.log(regions);
// => [
// {
// text: "Hello ",
// },
// {
// text: "world",
// formatting: {
// fontWeight: "bold";
// }
// },
// {
// text: ".",
// },
// ];
}
ts
#replaceTextfunction
Required

Replaces the text within the specified range.

Parameters

#boundsobject
Required

The range of text to replace.

#bounds.indexnumber
Required

The index of a character within the text content from which to start replacing the text. For example, a value of 0 will replace the text from the beginning of the text.

#bounds.lengthnumber
Required

The length of the text region to replace.

#charactersstring
Required

The replacement text.

#formattingobject
Optional

The formatting of the replaced text. To learn more, see Rich text formatting.

Example: Converting text to uppercase

for (const content of draft.contents) {
const regions = await content.readTextRegions();
for (const region of regions) {
content.replaceText(
{ index: 0, length: region.text.length },
region.text.toUpperCase()
);
}
}
ts

Videos

If the scope is "video", each object has the following properties:

#refstring
Required

An identifier that points to a video asset in Canva's backend.

#options.onChange(event.read().save())function
Required

Saves any changes made to the contents array and updates the user's design to reflect those changes.

When the scope of a selection is "richtext", an app can read and modify the formatting of the selected rich text. This section lists all of the available formatting options.

#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".

#decorationstring
Optional

The decoration applied to the text, which can be:

  • "none"
  • "underline"

The default value is "none".

#fontRefFontRef
Optional

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

#fontSizenumber
Optional

The size of the font, in pixels. In Canva editor, the size of the font is displayed as points, not pixels, so the number set in this property is not necessarily the number that appears in Canva.

#fontStylestring
Optional

The style of the font.

The available options include:

  • "normal"
  • "italic"

The default value is "normal".

#fontWeightstring
Optional

The weight (thickness) of the font.

The available options depend on the font, but are a subset of the following:

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

The default value is "normal".

#listLevelnumber
Optional

Specifies the indentation level of the list item within its list context.

#listMarkerstring
Optional

The style of list marker.

The available options include:

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

The default value is "none".

#strikethroughstring
Optional

Indicates whether the text has strikethrough styling.

The available options include:

  • "none"
  • "strikethrough"

The default value is "none".

#textAlignstring
Optional

The alignment of the text.

The available options include:

  • "start"
  • "center"
  • "end"
  • "justify"

The default value is "start".

Promise<void>