Rich controls

Some extensions, such as editing extensions, can render user interface components in the Canva editor. Canva refers to these components as rich controls. You can use rich controls to create heavily customized user experiences while still remaining aligned with Canva's design system.
This tutorial explains how to create and manage rich controls.
Step 1: Create a control
You can create controls with the create method:
1
canva.create("button", {
2
  id: "myButton",
3
  label: "My Button",
4
});
Copied!
This method accepts the following arguments:
The type of control
Properties for configuring the control
The available properties depend on the control, but at a minimum, all controls require an id property.
You can also use JSX to render controls. For more information, refer to JSX.
Step 2: Render a control in the control panel
Creating a control doesn't render the control in the control panel. You have to explicitly render controls in the control panel with the updateControlPanel method.
The updateControlPanel method accepts an array of controls as its only argument:
1
canva.updateControlPanel([
2
  canva.create("button", {
3
    id: "myButton",
4
    label: "My Button",
5
  }),
6
]);
Copied!
Canva renders the controls in the same order they appear in the array.
An extension must call the updateControlPanel method at various points throughout its lifecycle, including when adding, updating, and removing controls from the control panel.
Until an extension calls the updateControlPanel method:
The control panel remains in a "loading" state.
Canva doesn't render the Apply and Cancel buttons.
For this reason, extensions should call the updateControlPanel method in the onReady callback.
If necessary, an extension can render an empty control panel by passing an empty array into the updateControlPanel method.
Step 3: Detect control events
When a user interacts with a control, Canva emits an event. Your extension can listen for this event by registering a callback with the onControlsEvent method:
1
canva.onControlsEvent((opts) => {
2
  console.log(opts);
3
});
Copied!
This callback receives an opts object that contains information about the event. This object always contains a controlId and controlType property, which you can use to identify the control the user is interacting with:
1
canva.onControlsEvent((opts) => {
2
  if (opts.message.controlId === "myButton") {
3
    console.log("You clicked my button!");
4
  }
5
});
Copied!
For some controls, the opts object also contains the value of the control. You can access this value via the opts.message.message.value property:
1
canva.onControlsEvent((opts) => {
2
  if (opts.message.controlType === "slider") {
3
    console.log(event.message.message.value);
4
  }
5
});
Copied!
What happens when a user interacts with a control is the responsibility of the extension.
Step 4: Manage the state of controls
Controls don't maintain their own state. For example, if an extension renders a Select control, the default behavior means the user can't change the value of the control.
This is because, when a user interacts with a control, Canva doesn't:
Keep track of the control's value.
Re-render the control when its value changes.
Extensions are responsible for both of these tasks.
A common solution is store the values of controls in an object. Then, when a user interacts with a control, the extension can update the values in the object and re-render the controls. The following snippet demonstrates this pattern:
1
const canva = window.canva.init();
2
​
3
const state = {
4
  selectExample: "apples",
5
};
6
​
7
canva.onReady(async () => {
8
  // Render the control panel
9
  renderControls();
10
});
11
​
12
canva.onControlsEvent(async (opts) => {
13
  // Update the state object
14
  if (opts.message.controlType === "select") {
15
    state[opts.message.controlId] = opts.message.message.value;
16
  }
17
​
18
  // Re-render the control panel
19
  renderControls();
20
});
21
​
22
function renderControls() {
23
  // Define the controls
24
  const controls = [
25
    canva.create("select", {
26
      id: "selectExample",
27
      value: state.selectExample,
28
      options: [
29
        { value: "apples", label: "Apples" },
30
        { value: "bananas", label: "Bananas" },
31
        { value: "pears", label: "Pears" },
32
      ],
33
    }),
34
  ];
35
​
36
  // Update the control panel
37
  canva.updateControlPanel(controls);
38
}
Copied!
This is only a pattern though. You can use other techniques to manage the state of controls.
Step 5: Improve the performance of controls
Some controls, such as the color picker, emit a lot of events. This can cause performance issues if an extension re-renders controls (or performs some other action) for every event.
To avoid this problem, Canva passes a commit property into the onControlsEvent callback:
1
canva.onControlsEvent((opts) => {
2
  console.log(opts.message.commit);
3
});
Copied!
This property is false while the user is actively interacting with a control (for example, adjusting the value of a slider) and true once the user has finished interacting with a control.
You can use the commit property to return early from the onControlsEvent callback if the user is actively interacting with a control:
1
canva.onControlsEvent((opts) => {
2
  if (!opts.message.commit) {
3
    return;
4
  }
5
​
6
  console.log(opts);
7
});
Copied!
This significantly reduces the number of times Canva re-renders the controls.
The following controls emit an event with a commit property that may be false:
​ColorPicker​
​Slider​
For the rest of the controls that emit an event, the commit property is always true.
If it's important that users see real-time updates to their images, return early from the onControlsEvent callback after re-rendering the user's image but before re-rendering the controls.
Example
1
const canva = window.canva.init();
2
​
3
const state = {
4
  colorPickerExample: "#ff0099",
5
};
6
​
7
canva.onReady(async () => {
8
  renderControls();
9
});
10
​
11
canva.onControlsEvent(async (opts) => {
12
  if (!opts.message.commit) {
13
    return;
14
  }
15
​
16
  if (opts.message.controlType === "color_picker") {
17
    state[opts.message.controlId] = opts.message.message.value;
18
    document.body.style.backgroundColor = opts.message.message.value;
19
  }
20
​
21
  renderControls();
22
});
23
​
24
function renderControls() {
25
  const controls = [
26
    canva.create("color_picker", {
27
      id: "colorPickerExample",
28
      color: state.colorPickerExample,
29
    }),
30
  ];
31
​
32
  canva.updateControlPanel(controls);
33
}
Copied!

Frontend development - Previous

Notifications

Button

Last modified 6mo ago

Copy link

Contents

Step 1: Create a control

Step 2: Render a control in the control panel

Step 3: Detect control events

Step 4: Manage the state of controls

Step 5: Improve the performance of controls

Example