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