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

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

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.

Plaintext

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

textstring

Required

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:

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.