Creating providers

A provider is a data source that Canva's native features and apps can import data from.

This guide explains how to create a provider that:

• doesn't render a UI
• exposes a single data table

Step 1: Enable the Data Provider capability

Before an app can use the Data Provider capability, the capability must be enabled via the Developer Portal. This lets Canva know that it should be shown as a data source.

To enable the capability:

1. Navigate to an app via the Developer Portal.
2. On the Configure your app page, enable Data Provider.

Step 2: Access the Data Provider capability

Like all capabilities, Canva injects the Data Provider capability into the app's iframe and attaches it to the window object:

console.log(window.canva.dataProvider);

In the starter kit, we've included a getDataProvider function:

import { getDataProvider } from "@canva/data-provider";
const dataProvider = getDataProvider();
console.log(dataProvider); // => DataProvider

This function:

• Throws an error if the capability is unavailable
• Provides type-safety when using TypeScript

Step 3: Create a data table

A data table is the data structure that providers must use to expose data to consumers. By conforming to this structure, all providers are automatically compatible with all consumers.

At its most basic, a data table is a plain JavaScript object with the following properties:

• name
• columns

The name property is a human readable label for the data table, while the columns property is an array of objects that describe the table's columns and the values they contain.

This is an example of a data table that contains a list of Pokémon:

const pokemon = {
  name: "Pokemon",
  columns: [
    {
      type: "string",
      name: "Name",
      values: ["Pikachu", "Squirtle", "Bulbasaur", "Charmander"],
    },
    {
      type: "string",
      name: "Type",
      values: ["Electric", "Water", "Grass", "Fire"],
    },
    {
      type: "number",
      name: "Level",
      values: [42, 29, 32, 9],
    },
    {
      type: "boolean",
      name: "isCaptured",
      values: [true, true, false, true],
    },
    {
      type: "date",
      name: "capturedAt",
      values: [new Date(), new Date(), undefined, new Date()],
    },
  ],
};

For a complete explanation of data tables, see Data Tables.

Step 4: Handle the provider's selection

When a user attempts to import data via a consumer, such as Canva's Bulk Create feature, the user is prompted to select a provider. Your app must register a callback that runs when this selection happens.

To register the callback, call the onSelectDataTable method:

React.useEffect(() => {
  dataProvider.onSelectDataTable(async (opts) => {
    console.log(opts);
  });
}, []);

This callback receives an opts object as its only parameter. This object contains a selectDataTable method, which an app can use to send a data table to a consumer.

Step 5: Send the data table to a consumer

In the onSelectDataTable callback, call the selectDataTable method and pass through a data table as the only argument:

React.useEffect(() => {
  dataProvider.onSelectDataTable(async (opts) => {
    opts.selectDataTable(pokemon);
  });
}, []);

When a user selects the provider, the app will immediately send the data table to the consumer.