selection.registerOnChange

API reference for the selection.registerOnChange method.

Registers a callback that runs when a user selects (or deselects) an element containing a specific type of content.

To learn more, see:

import { selection } from "@canva/design";
(async () => {
await selection.registerOnChange({
scope: "text",
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 an element selection callback.

#options.scopestring
Required

The type of content that should trigger a selection event.

The available options include:

  • "image"
  • "text"
#options.onChangefunction
Required

The callback that runs when a user selects or deselects an element that contains 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 is determined by the scope passed in the options object.

#options.onChange(event.count)number
Required

The number of selected elements.

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

A function that returns:

  • An array of the selected elements
  • A method for persisting changes to those elements
#options.onChange(event.read().contents)array
Required

The content of the selected elements. Each element is represented as an object. To modify the content of those elements: loop through the elements, mutate their properties, and call the save method.

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

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

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

  • text - The text content of the element, as plain text.
#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.

Promise<void>