Skip navigation

Skip to main content

API reference
API reference

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);
  },
});
TS

Scopes

Before an app that uses this method can be submitted for review, the following scopes must be enabled through 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 scopes.

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.