Extensions with custom frontends, such as editing extensions, can show toast notifications to users. You can use these notifications to communicate important information, such as when a long-running task has finished or when an error has occurred.

This tutorial explains how to show notifications to users.

Step 1: Choose a notification type

An extension can display two types of notifications:

• Info

• Error

Both types of notifications look similar. The main difference is that error notifications are dismissible and remain on the screen for a longer period of time.

Step 2: Define the notification text

User-facing strings, including the text that appears in a notification, can't be embedded in the source code of the extension. This is because Canva must be able to:

• Verify that user-facing strings meet the UX guidelines.

• Localize user-facing strings for different regions.

To define user-facing strings, you must create a JSON file that contains all of the strings and upload this file to the Developer Portal, via the extension's Translations field.

The following snippet demonstrates the required structure of the JSON file:

{
  "en": [
    {
      "key": "greeting",
      "value": "Hello! I hope you're having a lovely day.",
      "translatorNote": "Label for notification when user opens the app."
    }
  ]
}

To learn more about the structure of this JSON file, refer to Translations.

Step 3: Show a notification

To show a notification, call the showNotification method:

const canva = window.canva.init();
​
canva.onReady(async (opts) => {
  canva.showNotification('greeting', 'info');
});

This method accepts two arguments:

• The key of a string defined in the Translations file.

• The notification type. (The default value is "info".)

You can call the showNotification method at any point in the lifecycle of the extension.

Example

index.js

const canva = window.canva.init();
​
canva.onReady(async () => {
  renderControls();
});
​
canva.onControlsEvent(async (opts) => {
  if (!opts.message.commit) {
    return;
  }
​
  if (opts.message.controlId === 'showInfo') {
    canva.showNotification('infoExample', 'info');
  }
​
  if (opts.message.controlId === 'showError') {
    canva.showNotification('errorExample', 'error');
  }
});
​
function renderControls() {
  const controls = [
    canva.create('button', {
      id: 'showInfo',
      label: 'Show info',
    }),
    canva.create('button', {
      id: 'showError',
      label: 'Show error',
    }),
  ];
​
  canva.updateControlPanel(controls);
}

labels.json

{
  "en": [
    {
      "key": "infoExample",
      "value": "This is an example of an 'info' notification.",
      "translatorNote": "Label to demonstrate an 'info' notification."
    },
    {
      "key": "errorExample",
      "value": "This is an example of an 'error' notification.",
      "translatorNote": "Label to demonstrate an 'error' notification."
    }
  ]
}