API reference

prepareDataConnector

API reference for the intents prepareDataConnector method.

Prepares a DataConnector Intent.

Usage

import { prepareDataConnector } from "@canva/intents/data";

prepareDataConnector({
 getDataTable: async (params) => {
   // Implement the logic to fetch the data table
 },
 renderSelectionUi: (params) => {
   // Implement the UI for the data table selection
 },
});

TSX

Parameters

implementationDataConnectorIntentRequired

Main interface for implementing the Data Connector intent.

Implementing the Data Connector intent enables apps to import external data into Canva. This allows users to select, preview, and refresh data from external sources.

getDataTablefunctionRequired

Gets structured data from an external source.

This action is called in two scenarios:

During data selection to preview data before import (when RenderSelectionUiRequest.updateDataRef is called).
When refreshing previously imported data (when the user requests an update).

Example: Getting data from an external source

import type { GetDataTableRequest, GetDataTableResponse } from '@canva/intents/data';

async function getDataTable(request: GetDataTableRequest): Promise<GetDataTableResponse> {
  const { dataSourceRef, limit, signal } = request;

  // Check if the operation has been aborted.
  if (signal.aborted) {
    return { status: 'app_error', message: 'The data fetch operation was cancelled.' };
  }

  // ... data fetching logic using dataSourceRef, limit, and signal ...

  // Placeholder for a successful result.
  return {
    status: 'completed',
    dataTable: { rows: [{ cells: [{ type: 'string', value: 'Fetched data' }] }] }
  };
}

Parameters

requestGetDataTableRequestRequired

Parameters for the data fetching operation.

dataSourceRefDataSourceRefRequired

Reference to the data source to fetch.

This contains the information needed to identify and retrieve the specific data that was previously selected by the user.

Use this to query your external data service.

sourcestringRequired

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestringOptional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

limitDataTableLimitRequired

Maximum row and column limits for the imported data.

Your app must ensure the returned data does not exceed these limits.

If the requested data would exceed these limits, either:

Truncate the data to fit within limits, or
Return a 'data_table_limit_exceeded' error

rownumberRequired

The maximum number of rows allowed.

Your app should ensure data does not exceed this limit.

columnnumberRequired

The maximum number of columns allowed.

Your app should ensure data does not exceed this limit.

signalAbortSignalRequired

Standard DOM AbortSignal for cancellation support.

Your app should monitor this signal and abort any ongoing operations if it becomes aborted.

Returns

A promise resolving to either a successful result with data or an error. This is a Promise that resolves with the following object:

Successful result from getDataTable action.

statusstring

Indicates the operation completed successfully

This must be "completed".

dataTableDataTable

The fetched data formatted as a data table.

rowsDataTableRow[]

The data rows containing the actual values.

Each row contains an array of cells with typed data values.

cellsDataTableCell<DataType>[]

Array of cells containing the data values.

Each cell must have a type that matches the corresponding column definition (if provided).

columnConfigsColumnConfig[]Optional

Column definitions with names and data types.

These help Canva interpret and display your data correctly.

namestring | undefined

Name for the column, displayed as header text.

If undefined, the column will have no header text.

typeobject

Expected data type for cells in this column.

Use a specific DataType for columns with consistent types, or 'variant' for columns that may contain mixed types.

Data types supported for table cells.

Available values:

"string"
"number"
"date"
"boolean"
"media"

This must be "variant".

metadataDataTableMetadataOptional

Optional metadata providing additional context about the data.

descriptionstringOptional

A human-readable description of the dataset.

This description helps users understand what data they are importing.

providerInfoobjectOptional

Information about the data provider or source.

namestring

Name of the data provider.

urlstringOptional

URL to the provider's website or related resource.

Error results that can be returned from getDataTable method.

GetDataTableError indicating the data source reference is no longer valid. This will trigger a re-selection flow for the user.

statusstring

The data source reference is no longer valid.

Return this error when the DataSourceRef cannot be used to retrieve data, for example:

The referenced dataset has been deleted
Access permissions have changed
The structure of the data has fundamentally changed

This will trigger a re-selection flow, allowing the user to choose a new data source.

This must be "outdated_source_ref".

GetDataTableError indicating failure to fetch data from the external source. Typically due to network issues or API failures.

statusstring

Failed to fetch data from the external source.

Return this error for network issues, API failures, or other connectivity problems that prevent data retrieval.

This must be "remote_request_failed".

GetDataTableError indicating custom error occurred in the app's implementation. This can be used to indicate specific issues that are not covered by other error types.

statusstring

A custom error occurred in your app.

Return this for application-specific errors that don't fit the other categories. Include a descriptive message explaining the error to the user.

This must be "app_error".

messagestringOptional

Optional message explaining the error.

renderSelectionUifunctionRequired

Renders a user interface for selecting and configuring data from your external sources.

Example: Rendering a data selection UI

import type { RenderSelectionUiRequest } from '@canva/intents/data';

async function renderSelectionUi(request: RenderSelectionUiRequest): Promise<void> {
  // UI rendering logic.
  // Example: if user selects data 'ref123'.
  const selectedRef = { source: 'ref123', title: 'My Selected Table' };
  try {
    const result = await request.updateDataRef(selectedRef);
    if (result.status === 'completed') {
      console.log('Selection valid and preview updated.');
    } else {
      console.error('Selection error:', result.status);
    }
  } catch (error) {
     console.error('An unexpected error occurred during data ref update:', error);
  }
}

Parameters

requestRenderSelectionUiRequestRequired

Configuration and callbacks for the data selection UI.

invocationContextInvocationContextRequired

Context information about why the data selection UI is being launched.

Use this to adapt your UI for different scenarios:

'data_selection': Initial data selection or editing existing data
'outdated_source_ref': Previous reference is no longer valid, guide user to reselect
'app_error': Custom error occurred, show error message and recovery options

When dataSourceRef is provided, pre-populate your UI with this selection.

InvocationContext indicating initial data selection flow or edit of existing data.

reasonstringRequired

Initial data selection or editing existing data.

This is the standard flow when:

A user is selecting data for the first time
A user is editing a previous selection

If dataSourceRef is provided, this indicates an edit flow, and you should pre-populate your UI with this selection.

This must be "data_selection".

dataSourceRefDataSourceRefOptional

If dataSourceRef is provided, this is an edit of existing data flow and UI should be pre-populated.

sourcestringRequired

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestringOptional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

InvocationContext indicating an error occurred because the previously selected data source reference is no longer valid. Triggered when getDataTable returned 'outdated_source_ref' during data refresh. UI should guide the user to reselect or reconfigure their data.

reasonstringRequired

Previously selected data source reference is no longer valid.

This occurs when getDataTable returned 'outdated_source_ref' during a refresh attempt. Your UI should guide the user to select a new data source or update their selection.

The outdated reference is provided to help you suggest an appropriate replacement.

This must be "outdated_source_ref".

dataSourceRefDataSourceRefOptional

The outdated data source reference that caused the error during refresh.

sourcestringRequired

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestringOptional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

InvocationContext indicating a custom error occurred during data refresh. Triggered when getDataTable returned 'app_error' status. UI should display the error message and help users recover.

reasonstringRequired

A custom error occurred during data refresh.

This occurs when getDataTable returned 'app_error' during a refresh attempt. Your UI should display the error message and help users recover from the specific issue.

This must be "app_error".

dataSourceRefDataSourceRefOptional

The data source reference that caused the error during refresh.

sourcestringRequired

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestringOptional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

messagestringOptional

The error message to display to the user.

limitDataTableLimitRequired

Maximum allowed rows and columns for the imported data.

Your UI should inform users of these constraints and prevent or warn about selections that would exceed them. This helps users understand why certain data sets might not be available for selection.

rownumberRequired

The maximum number of rows allowed.

Your app should ensure data does not exceed this limit.

columnnumberRequired

The maximum number of columns allowed.

Your app should ensure data does not exceed this limit.

updateDataReffunctionRequired

Callback to preview selected data before finalizing import.

Call this function when the user selects data to:

Show a preview of the selected data to the user
Validate that the selection meets system requirements

Calling this function will trigger your getDataTable implementation. Wait for the promise to resolve to determine if the selection is valid.

Throws

Will throw CanvaError('bad_request') if

DataSourceRef.source exceeds 5kb.
DataSourceRef.title exceeds 255 characters.
GetDataTableCompleted.dataTable exceeds DataTableLimit or contains invalid data.

Parameters

dataSourceRefDataSourceRefRequired

Reference object identifying the selected data

sourcestringRequired

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestringOptional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

Returns

Promise resolving to success or an error result. This is a Promise that resolves with the following object:

Successful result from the RenderSelectionUiRequest.updateDataRef callback.

statusstring

The data selection was successful and can be previewed.

This must be "completed".

Error results that can be returned from getDataTable method.

GetDataTableError indicating the data source reference is no longer valid. This will trigger a re-selection flow for the user.

statusstring

The data source reference is no longer valid.

Return this error when the DataSourceRef cannot be used to retrieve data, for example:

The referenced dataset has been deleted
Access permissions have changed
The structure of the data has fundamentally changed

This will trigger a re-selection flow, allowing the user to choose a new data source.

This must be "outdated_source_ref".

GetDataTableError indicating failure to fetch data from the external source. Typically due to network issues or API failures.

statusstring

Failed to fetch data from the external source.

Return this error for network issues, API failures, or other connectivity problems that prevent data retrieval.

This must be "remote_request_failed".

GetDataTableError indicating custom error occurred in the app's implementation. This can be used to indicate specific issues that are not covered by other error types.

statusstring

A custom error occurred in your app.

Return this for application-specific errors that don't fit the other categories. Include a descriptive message explaining the error to the user.

This must be "app_error".

messagestringOptional

Optional message explaining the error.

Returns

void

Returns

void