selection.registerOnChange

API reference for the selection.registerOnChange method.

This version of the API is deprecated. This version will soon be unsupported. You should use a stable version of the API in your app.

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

To learn more, see:

Usage

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

await selection.registerOnChange({
  scope: "plaintext",
  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

optionsobjectRequired

The options for registering a selection callback.

options.scopestringRequired

The type of content that should trigger a selection event.

The available options include:

"image"
"plaintext"
"richtext"
"video"

options.onChangefunctionRequired

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

options.onChange(event)objectRequired

The selection event.

options.onChange(event.scope)stringRequired

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

options.onChange(event.count)numberRequired

The number of distinct pieces of content that are selected.

options.onChange(event.read())functionRequired

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)arrayRequired

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:

refstringRequired

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

Plaintext

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

textstringRequired

The text content, as plaintext.

Richtext

If the scope is "richtext", each object is a RichtextRange. This is the same object that's returned by the createRichtextRange method.

Videos

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

refstringRequired

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

options.onChange(event.read().save())functionRequired

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