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:

Usage

import { selection } from "@canva/design";

await selection.registerOnChange({
  scope: "text",
  onChange: (event) => {
    console.log(event);
  },
});

Permissions

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.

Parameters

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

Returns

Promise<void>