onControlsEvent

API reference for the "onControlsEvent" method.

Registers a callback that runs when the user interacts with a rich control.

In this callback, an extension should:

  • Handle the user's input (for example, apply an effect to the user's image).

  • Track the state of controls (for example, the value of a Slider control).

  • Re-render the rich controls when the state changes.

Usage

const canva = window.canva.init();
const state = {
clicks: 0,
};
canva.onReady(() => {
renderControls();
});
canva.onControlsEvent(async (opts) => {
if (opts.message.controlId === "exampleButton") {
state.clicks = state.clicks + 1;
}
renderControls();
});
function renderControls() {
const controls = [
canva.create("button", {
id: "exampleButton",
label: `${state.clicks} clicks`,
}),
];
canva.updateControlPanel(controls);
}

Parameters

Name

Type

Required

Description

handler

ControlsEventHandler

Yes

The callback that runs when the user interacts with a control.

Returns

void

Types

ControlsEventHandler

The callback that runs when the user interacts with a control.

Signature

(opts) => void

Parameters

Name

Type

Required

Description

opts

object

Yes

Information about the event.

opts.message

object

Yes

Information about the event.

opts.message.commit

boolean

Yes

If false, the user is interacting with the control. If true, the user has finished interacting with the control.

opts.message.controlId

string

Yes

The ID of the control that triggered the event.

opts.message.controlType

string

Yes

The type of control that triggered the event.

opts.message.message

object

Yes

Additional information about the event. The available properties depend on the control.

Returns

void