> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# prepareDataConnector

API reference for the intents prepareDataConnector method.

Prepares a DataConnector Intent.

## Usage

```tsx
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
 },
});
```

## Parameters

<Prop.List>
  <Prop name="implementation" required type="DataConnectorIntent" sourceLineNumbers={[1033]}>
    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.

    <PillAccordion defaultExpanded={true} title={<>Properties of <strong>implementation</strong></>}>
      <Prop.List>
        <Prop name="getDataTable" required type="function" sourceLineNumbers={[194]}>
          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).

          <Prop.Extras>
            **Example: Getting data from an external source**

            ```ts
            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' }] }] }
              };
            }
            ```
          </Prop.Extras>

          **Parameters**

          <Prop.List>
            <Prop name="request" required type="GetDataTableRequest" sourceLineNumbers={[194]}>
              Parameters for the data fetching operation.

              <PillAccordion defaultExpanded={false} title={<>Properties of <strong>request</strong></>}>
                <Prop.List>
                  <Prop name="dataSourceRef" required type="DataSourceRef" sourceLineNumbers={[604]}>
                    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.

                    <PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
                      <Prop.List>
                        <Prop name="source" required type="string" sourceLineNumbers={[309]}>
                          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
                        </Prop>

                        <Prop name="title" type="string" sourceLineNumbers={[318]}>
                          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
                        </Prop>
                      </Prop.List>
                    </PillAccordion>
                  </Prop>

                  <Prop name="limit" required type="DataTableLimit" sourceLineNumbers={[615]}>
                    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

                    <PillAccordion defaultExpanded={false} title={<>Properties of <strong>limit</strong></>}>
                      <Prop.List>
                        <Prop name="row" required type="number" sourceLineNumbers={[425]}>
                          The maximum number of rows allowed.

                          Your app should ensure data does not exceed this limit.
                        </Prop>

                        <Prop name="column" required type="number" sourceLineNumbers={[431]}>
                          The maximum number of columns allowed.

                          Your app should ensure data does not exceed this limit.
                        </Prop>
                      </Prop.List>
                    </PillAccordion>
                  </Prop>

                  <Prop name="signal" required type="AbortSignal" sourceLineNumbers={[621]}>
                    Standard DOM AbortSignal for cancellation support.

                    Your app should monitor this signal and abort any ongoing operations if it becomes aborted.
                  </Prop>
                </Prop.List>
              </PillAccordion>
            </Prop>
          </Prop.List>

          **Returns**

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

          <Tabs>
            <Tab name="GetDataTableCompleted">
              Successful result from `getDataTable` action.

              <Prop.List>
                <Prop name="status" required type="string" sourceLineNumbers={[574]}>
                  Indicates the operation completed successfully

                  The only valid value is `"completed"`.
                </Prop>

                <Prop name="dataTable" required type="DataTable" sourceLineNumbers={[578]}>
                  The fetched data formatted as a data table.

                  <PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataTable</strong></>}>
                    <Prop.List>
                      <Prop name="rows" required type="DataTableRow[]" sourceLineNumbers={[372]}>
                        The data rows containing the actual values.

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

                        <PillAccordion defaultExpanded={false} title={<>Properties of <strong>rows</strong></>}>
                          <Prop.List>
                            <Prop name="cells" required type="DataTableCell<DataType>[]" sourceLineNumbers={[483]}>
                              Array of cells containing the data values.

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

                              <Tabs>
                                <Tab name="date">
                                  Cell containing a date value.

                                  <Prop.Extras>
                                    **Example: Creating a date cell**

                                    ```ts
                                    import type { DateDataTableCell } from '@canva/intents/data';

                                    const todayCell: DateDataTableCell = {
                                      type: 'date',
                                      value: Math.floor(Date.now() / 1000) // Unix timestamp in seconds
                                    };

                                    const emptyDateCell: DateDataTableCell = {
                                      type: 'date',
                                      value: undefined
                                    };
                                    ```
                                  </Prop.Extras>

                                  <Prop.List>
                                    <Prop name="type" required type="string" sourceLineNumbers={[542]}>
                                      Indicates this cell contains a date value.

                                      The only valid value is `"date"`.
                                    </Prop>

                                    <Prop name="value" required type="number | undefined" sourceLineNumbers={[548]}>
                                      Unix timestamp in seconds representing the date.

                                      Use `undefined` for an empty cell.
                                    </Prop>
                                  </Prop.List>
                                </Tab>

                                <Tab name="string">
                                  Cell containing a text value.

                                  <Prop.Extras>
                                    **Example: Creating a string cell**

                                    ```ts
                                    import type { StringDataTableCell } from '@canva/intents/data';

                                    const nameCell: StringDataTableCell = {
                                      type: 'string',
                                      value: 'John Doe'
                                    };

                                    const emptyStringCell: StringDataTableCell = {
                                      type: 'string',
                                      value: undefined
                                    };
                                    ```
                                  </Prop.Extras>

                                  <Prop.List>
                                    <Prop name="type" required type="string" sourceLineNumbers={[1172]}>
                                      Indicates this cell contains a string value.

                                      The only valid value is `"string"`.
                                    </Prop>

                                    <Prop name="value" required type="string | undefined" sourceLineNumbers={[1180]}>
                                      Text content of the cell.

                                      Maximum length: 10,000 characters

                                      Use `undefined` for an empty cell.
                                    </Prop>
                                  </Prop.List>
                                </Tab>

                                <Tab name="number">
                                  Cell containing a numeric value.

                                  <Prop.Extras>
                                    **Example: Creating a number cell**

                                    ```ts
                                    import type { NumberCellMetadata, NumberDataTableCell } from '@canva/intents/data';

                                    const priceCell: NumberDataTableCell = {
                                      type: 'number',
                                      value: 29.99,
                                      metadata: { formatting: '[$$]#,##0.00' }
                                    };

                                    const quantityCell: NumberDataTableCell = {
                                      type: 'number',
                                      value: 150
                                    };

                                    const emptyNumberCell: NumberDataTableCell = {
                                      type: 'number',
                                      value: undefined
                                    };
                                    ```
                                  </Prop.Extras>

                                  <Prop.List>
                                    <Prop name="type" required type="string" sourceLineNumbers={[939]}>
                                      Indicates this cell contains a number value.

                                      The only valid value is `"number"`.
                                    </Prop>

                                    <Prop name="value" required type="number | undefined" sourceLineNumbers={[954]}>
                                      Numeric value within safe integer range.

                                      Valid range: `Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`

                                      Invalid values:

                                      * Infinity or -Infinity
                                      * NaN
                                      * Negative zero (-0)
                                      * Denormalized numbers

                                      Use `undefined` for an empty cell.
                                    </Prop>

                                    <Prop name="metadata" type="NumberCellMetadata" sourceLineNumbers={[966]}>
                                      Optional formatting information for displaying the number.

                                      <Prop.Extras>
                                        **Example: Applying display formatting to a number**

                                        ```ts
                                        import type { NumberCellMetadata } from '@canva/intents/data';

                                        const currencyFormatting: NumberCellMetadata = { formatting: '[$USD]#,##0.00' };
                                        const percentageFormatting: NumberCellMetadata = { formatting: '0.00%' };
                                        ```
                                      </Prop.Extras>

                                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>metadata</strong></>}>
                                        <Prop.List>
                                          <Prop name="formatting" type="string" sourceLineNumbers={[907]}>
                                            Formatting pattern using Office Open XML Format.

                                            These patterns control how numbers are displayed to users,
                                            including currency symbols, decimal places, and separators.
                                          </Prop>
                                        </Prop.List>
                                      </PillAccordion>
                                    </Prop>
                                  </Prop.List>
                                </Tab>

                                <Tab name="boolean">
                                  Cell containing a boolean value.

                                  <Prop.Extras>
                                    **Examples**

                                    **Creating a boolean cell**

                                    ```ts
                                    import type { BooleanDataTableCell } from '@canva/intents/data';

                                    const isActiveCell: BooleanDataTableCell = {
                                      type: 'boolean',
                                      value: true
                                    };
                                    ```

                                    **Creating a boolean cell with false value**

                                    ```ts
                                    import type { BooleanDataTableCell } from '@canva/intents/data';

                                    const isCompleteCell: BooleanDataTableCell = {
                                      type: 'boolean',
                                      value: false
                                    };
                                    ```

                                    **Creating an empty boolean cell**

                                    ```ts
                                    import type { BooleanDataTableCell } from '@canva/intents/data';

                                    const emptyBooleanCell: BooleanDataTableCell = {
                                      type: 'boolean',
                                      value: undefined
                                    };
                                    ```
                                  </Prop.Extras>

                                  <Prop.List>
                                    <Prop name="type" required type="string" sourceLineNumbers={[124]}>
                                      Indicates this cell contains a boolean value.

                                      The only valid value is `"boolean"`.
                                    </Prop>

                                    <Prop name="value" required type="boolean | undefined" sourceLineNumbers={[130]}>
                                      Boolean value (true or false).

                                      Use `undefined` for an empty cell.
                                    </Prop>
                                  </Prop.List>
                                </Tab>

                                <Tab name="media">
                                  Cell containing a media collection (images and videos) value. A media cell can also contain
                                  references to media that is already imported into the user's Canva media library
                                  (`image_reference` / `video_reference`).

                                  <Prop.Extras>
                                    **Examples**

                                    **Creating a media cell with an image**

                                    ```ts
                                    import type { MediaCollectionDataTableCell } from '@canva/intents/data';

                                    const mediaCell: MediaCollectionDataTableCell = {
                                      type: 'media',
                                      value: [{
                                        type: 'image_upload',
                                        url: 'https://www.canva.dev/example-assets/image-import/image.jpg',
                                        mimeType: 'image/jpeg',
                                        thumbnailUrl: 'https://www.canva.dev/example-assets/image-import/thumbnail.jpg',
                                        aiDisclosure: 'none'
                                      }]
                                    };
                                    ```

                                    **Creating an empty media cell**

                                    ```ts
                                    import type { MediaCollectionDataTableCell } from '@canva/intents/data';

                                    const emptyMediaCell: MediaCollectionDataTableCell = {
                                      type: 'media',
                                      value: []
                                    };
                                    ```
                                  </Prop.Extras>

                                  <Prop.List>
                                    <Prop name="type" required type="string" sourceLineNumbers={[850]}>
                                      Indicates this cell contains a media collection.

                                      The only valid value is `"media"`.
                                    </Prop>

                                    <Prop name="value" required type="object[]" sourceLineNumbers={[856]}>
                                      Media collection values.

                                      Use empty array for an empty cell.

                                      <Tabs>
                                        <Tab name="DataTableImageUpload">
                                          Options for uploading an image asset to the user's private media library.

                                          <Prop.List>
                                            <Prop name="type" required type="string" sourceLineNumbers={[412]}>
                                              Indicates this value contains options for image uploading.

                                              The only valid value is `"image_upload"`.
                                            </Prop>

                                            <Prop name="url" required type="string" sourceLineNumbers={[743]}>
                                              The URL of the image file to upload.
                                              This can be an external URL or a data URL.

                                              Requirements for external URLs:

                                              * Must use HTTPS
                                              * Must return a `200` status code
                                              * `Content-Type` must match the file's MIME type
                                              * Must be publicly accessible (i.e. not a localhost URL)
                                              * Must not redirect
                                              * Must not contain an IP address
                                              * Maximum length: 4096 characters
                                              * Must not contain whitespace
                                              * Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
                                              * Maximum file size: 50MB

                                              Requirements for data URLs:

                                              * Must include `;base64` for base64-encoded data
                                              * Maximum size: 10MB (10 × 1024 × 1024 characters)

                                              Requirements for SVGs:

                                              * Disallowed elements:
                                                * `a`
                                                * `altglyph`
                                                * `altglyphdef`
                                                * `altglyphitem`
                                                * `animate`
                                                * `animatemotion`
                                                * `animatetransform`
                                                * `cursor`
                                                * `discard`
                                                * `font`
                                                * `font-face`
                                                * `font-face-format`
                                                * `font-face-name`
                                                * `font-face-src`
                                                * `font-face-uri`
                                                * `foreignobject`
                                                * `glyph`
                                                * `glyphref`
                                                * `missing-glyph`
                                                * `mpath`
                                                * `script`
                                                * `set`
                                                * `switch`
                                                * `tref`
                                              * Disallowed attributes:
                                                * `crossorigin`
                                                * `lang`
                                                * `media`
                                                * `onload`
                                                * `ping`
                                                * `referrerpolicy`
                                                * `rel`
                                                * `rendering-intent`
                                                * `requiredextensions`
                                                * `requiredfeatures`
                                                * `systemlanguage`
                                                * `tabindex`
                                                * `transform-origin`
                                                * `unicode`
                                                * `vector-effect`
                                              * The `href` attribute of an `image` element only supports data URLs for PNG and JPEG images.
                                              * The URL in the `href` attribute must not point to a location outside of the SVG.
                                              * The `style` attribute must not use the `mix-blend-mode` property.
                                            </Prop>

                                            <Prop name="mimeType" required type="ImageMimeType" sourceLineNumbers={[747]}>
                                              The MIME type of the image file.

                                              <Prop.Extras>
                                                **Available values**:

                                                * `"image/jpeg"`
                                                * `"image/heic"`
                                                * `"image/png"`
                                                * `"image/svg+xml"`
                                                * `"image/webp"`
                                                * `"image/tiff"`
                                              </Prop.Extras>
                                            </Prop>

                                            <Prop name="thumbnailUrl" required type="string" sourceLineNumbers={[765]}>
                                              The URL of a thumbnail image to display while the image is queued for upload.
                                              This can be an external URL or a data URL.

                                              Requirements for external URLs:

                                              * Must use HTTPS
                                              * Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
                                              * Must be a PNG, JPEG, or SVG file
                                              * Maximum length: 4096 characters

                                              Requirements for data URLs:

                                              * Must include `;base64` for base64-encoded data
                                              * Maximum size: 10MB (10 × 1024 × 1024 characters)
                                            </Prop>

                                            <Prop name="aiDisclosure" required type="AiDisclosure" sourceLineNumbers={[805]}>
                                              A disclosure identifying if the app generated this image using AI

                                              Helps users make informed decisions about the content they interact with.
                                              See AiDisclosure for the full definition.

                                              **App Generated**

                                              'app\_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
                                              the app requests a third-party service to take similar action on an image using AI.

                                              Required for the following cases (this list is not exhaustive):

                                              | Case                                                            | Reason                               |
                                              | --------------------------------------------------------------- | ------------------------------------ |
                                              | AI generates a new image from scratch                           | Creates new creative content         |
                                              | AI changes the style of the image e.g. makes it cartoon         | Significantly alters the style       |
                                              | AI removes an object and replaces it with new content           | Creates new creative content         |
                                              | AI changes the facial expression of a person in an image        | Can alter content's original meaning |
                                              | AI composites multiple images together                          | Significantly alters context         |
                                              | AI expands an image by generating new content to fill the edges | Creates new creative content         |
                                              | AI replaces background by generating new content                | Creates new creative content         |

                                              **None**

                                              'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request
                                              to third-party hosted content.

                                              Required for the following cases (this list is not exhaustive):

                                              | Case                                               | Reason                                    |
                                              | -------------------------------------------------- | ----------------------------------------- |
                                              | Asset comes from an asset library                  | Didn't generate the asset itself          |
                                              | AI corrects red eyes                               | A minor correction                        |
                                              | AI removes background without replacement          | Doesn't change original meaning by itself |
                                              | AI changes the color of an object in an image      | Doesn't change original meaning by itself |
                                              | AI detects image defects and suggests manual fixes | Didn't change the asset itself            |
                                              | AI adjusts brightness and contrast on an image     | Doesn't change original meaning by itself |
                                              | AI upscales an image                               | Doesn't change original meaning by itself |

                                              <Prop.Extras>
                                                **Available values**:

                                                * `"app_generated"`
                                                * `"none"`
                                              </Prop.Extras>
                                            </Prop>

                                            <Prop name="name" type="string" sourceLineNumbers={[665]}>
                                              A human-readable name for the image asset.

                                              This name is displayed in the user's media library and helps users identify
                                              and find the asset later. If not provided, Canva will generate a name based
                                              on the asset's URL or a unique identifier.

                                              Requirements:

                                              * Minimum length: 1 character (empty strings are not allowed)
                                              * Maximum length: 255 characters
                                            </Prop>
                                          </Prop.List>
                                        </Tab>

                                        <Tab name="DataTableVideoUpload">
                                          Options for uploading a video asset to the user's private media library.

                                          <Prop.List>
                                            <Prop name="type" required type="string" sourceLineNumbers={[510]}>
                                              Indicates this value contains options for video uploading.

                                              The only valid value is `"video_upload"`.
                                            </Prop>

                                            <Prop name="url" required type="string" sourceLineNumbers={[1265]}>
                                              The URL of the video file to upload.

                                              Requirements:

                                              * Must use HTTPS
                                              * Must return a `200` status code
                                              * `Content-Type` must match the file's MIME type
                                              * Must be publicly accessible (i.e. not a localhost URL)
                                              * Must not redirect
                                              * Must not contain an IP address
                                              * Maximum length: 4096 characters
                                              * Must not contain whitespace
                                              * Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
                                              * Maximum file size: 1000MB (1GB)
                                            </Prop>

                                            <Prop name="mimeType" required type="VideoMimeType" sourceLineNumbers={[1269]}>
                                              The MIME type of the video file.

                                              <Prop.Extras>
                                                **Available values**:

                                                * `"video/avi"`
                                                * `"video/x-msvideo"`
                                                * `"image/gif"`
                                                * `"video/x-m4v"`
                                                * `"video/x-matroska"`
                                                * `"video/quicktime"`
                                                * `"video/mp4"`
                                                * `"video/mpeg"`
                                                * `"video/webm"`
                                                * `"application/json"`
                                              </Prop.Extras>
                                            </Prop>

                                            <Prop name="thumbnailImageUrl" required type="string" sourceLineNumbers={[1301]}>
                                              The URL of a thumbnail image to use as a fallback if `thumbnailVideoUrl` isn't provided.
                                              This can be an external URL or a data URL.

                                              Requirements for external URLs:

                                              * Must use HTTPS
                                              * Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
                                              * Must be a PNG, JPEG, or SVG file
                                              * Maximum length: 4096 characters

                                              Requirements for data URLs:

                                              * Must include `;base64` for base64-encoded data
                                              * Maximum size: 10MB (10 × 1024 × 1024 characters)
                                              * The dimensions of the thumbnail must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
                                            </Prop>

                                            <Prop name="aiDisclosure" required type="AiDisclosure" sourceLineNumbers={[1339]}>
                                              A disclosure identifying if the app generated this video using AI.

                                              Helps users make informed decisions about the content they interact with.
                                              See AiDisclosure for the full definition.

                                              **App Generated**

                                              'app\_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
                                              the app requests a third-party service to take similar action on a video using AI.

                                              Required for the following cases (this list is not exhaustive):

                                              | Case                                                           | Reason                         |
                                              | -------------------------------------------------------------- | ------------------------------ |
                                              | AI generates a new video from scratch                          | Creates new creative content   |
                                              | AI changes the style of the video e.g. makes it cartoon        | Significantly alters the style |
                                              | AI adds subtitles that rely on subjective interpretation       | Creates new creative content   |
                                              | AI expands a video by generating new content to fill the edges | Creates new creative content   |
                                              | AI animates an image                                           | Creates new creative content   |
                                              | AI fixes defects e.g. blur in a video by generating details    | Creates new creative content   |
                                              | AI generates a talking head presenter                          | Creates new creative content   |

                                              **None**

                                              'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of
                                              a request to third-party hosted content.

                                              Required for the following cases (this list is not exhaustive):

                                              | Case                                                     | Reason                                    |
                                              | -------------------------------------------------------- | ----------------------------------------- |
                                              | Asset comes from an asset library                        | Didn't generate the asset itself          |
                                              | AI corrects red eyes                                     | A minor correction                        |
                                              | AI adjusts brightness and contrast on a video            | Doesn't change original meaning by itself |
                                              | AI creates a slow motion effect in a video               | Doesn't change original meaning by itself |
                                              | AI adds AI word-by-word transcribed subtitles to a video | Doesn't change original meaning by itself |

                                              <Prop.Extras>
                                                **Available values**:

                                                * `"app_generated"`
                                                * `"none"`
                                              </Prop.Extras>
                                            </Prop>

                                            <Prop name="name" type="string" sourceLineNumbers={[1240]}>
                                              A human-readable name for the video asset.

                                              This name is displayed in the user's media library and helps users identify
                                              and find the asset later. If not provided, Canva will generate a name based
                                              on the asset's URL or a unique identifier.

                                              Requirements:

                                              * Minimum length: 1 character (empty strings are not allowed)
                                              * Maximum length: 255 characters
                                            </Prop>

                                            <Prop name="thumbnailVideoUrl" type="string" sourceLineNumbers={[1282]}>
                                              The URL of a thumbnail video to display while the video is queued for upload.

                                              Requirements:

                                              * Must use HTTPS
                                              * Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
                                              * Maximum length: 4096 characters
                                              * The dimensions of the thumbnail video must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
                                              * Must not be an AVI file. Although our APIs support uploading AVI videos, Canva can't preview them because of native support of browsers
                                            </Prop>
                                          </Prop.List>
                                        </Tab>

                                        <Tab name="DataTableImageReference">
                                          A reference to an image already imported into the user's Canva media library. `requestDataTable`
                                          returns Data Connector media as references; pass them through unchanged to `autofillDesign`
                                          or `requestDataFieldMatching`.

                                          <Prop.List>
                                            <Prop name="type" required type="string" sourceLineNumbers={[397]}>
                                              Indicates this value references an already-imported image.

                                              The only valid value is `"image_reference"`.
                                            </Prop>

                                            <Prop name="ref" required type="string" sourceLineNumbers={[401]}>
                                              Opaque Canva media reference. Treat as a handle — do not construct or parse it.
                                            </Prop>
                                          </Prop.List>
                                        </Tab>

                                        <Tab name="DataTableVideoReference">
                                          A reference to a video already imported into the user's Canva media library.
                                          See DataTableImageReference.

                                          <Prop.List>
                                            <Prop name="type" required type="string" sourceLineNumbers={[495]}>
                                              Indicates this value references an already-imported video.

                                              The only valid value is `"video_reference"`.
                                            </Prop>

                                            <Prop name="ref" required type="string" sourceLineNumbers={[499]}>
                                              Opaque Canva media reference. Treat as a handle — do not construct or parse it.
                                            </Prop>
                                          </Prop.List>
                                        </Tab>
                                      </Tabs>
                                    </Prop>
                                  </Prop.List>
                                </Tab>
                              </Tabs>
                            </Prop>
                          </Prop.List>
                        </PillAccordion>
                      </Prop>

                      <Prop name="columnConfigs" type="ColumnConfig[]" sourceLineNumbers={[366]}>
                        Column definitions with names and data types.

                        These help Canva interpret and display your data correctly.

                        <PillAccordion defaultExpanded={false} title={<>Properties of <strong>columnConfigs</strong></>}>
                          <Prop.List>
                            <Prop name="name" required type="string | undefined" sourceLineNumbers={[143]}>
                              Name for the column, displayed as header text.

                              If `undefined`, the column will have no header text.
                            </Prop>

                            <Prop name="type" required type="object" sourceLineNumbers={[150]}>
                              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.

                              <Tabs>
                                <Tab name="DataType">
                                  Data types supported for table cells.

                                  <Prop.Extras>
                                    **Available values**:

                                    * `"string"`
                                    * `"number"`
                                    * `"date"`
                                    * `"boolean"`
                                    * `"media"`
                                  </Prop.Extras>
                                </Tab>

                                <Tab name="string">
                                  The only valid value is `"variant"`.
                                </Tab>
                              </Tabs>
                            </Prop>
                          </Prop.List>
                        </PillAccordion>
                      </Prop>
                    </Prop.List>
                  </PillAccordion>
                </Prop>

                <Prop name="metadata" type="DataTableMetadata" sourceLineNumbers={[582]}>
                  Optional metadata providing additional context about the data.

                  <PillAccordion defaultExpanded={false} title={<>Properties of <strong>metadata</strong></>}>
                    <Prop.List>
                      <Prop name="description" type="string" sourceLineNumbers={[444]}>
                        A human-readable description of the dataset.

                        This description helps users understand what data they are importing.
                      </Prop>

                      <Prop name="providerInfo" type="object" sourceLineNumbers={[448]}>
                        Information about the data provider or source.

                        <PillAccordion defaultExpanded={false} title={<>Properties of <strong>providerInfo</strong></>}>
                          <Prop.List>
                            <Prop name="name" required type="string" sourceLineNumbers={[452]}>
                              Name of the data provider.
                            </Prop>

                            <Prop name="url" type="string" sourceLineNumbers={[456]}>
                              URL to the provider's website or related resource.
                            </Prop>
                          </Prop.List>
                        </PillAccordion>
                      </Prop>
                    </Prop.List>
                  </PillAccordion>
                </Prop>
              </Prop.List>
            </Tab>

            <Tab name="GetDataTableError">
              Error results that can be returned from `getDataTable` method.

              <Tabs>
                <Tab name="OutdatedSourceRefError">
                  GetDataTableError indicating the data source reference is no longer valid.
                  This will trigger a re-selection flow for the user.

                  <Prop.List>
                    <Prop name="status" required type="string" sourceLineNumbers={[988]}>
                      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.

                      The only valid value is `"outdated_source_ref"`.
                    </Prop>
                  </Prop.List>
                </Tab>

                <Tab name="RemoteRequestFailedError">
                  GetDataTableError indicating failure to fetch data from the external source.
                  Typically due to network issues or API failures.

                  <Prop.List>
                    <Prop name="status" required type="string" sourceLineNumbers={[1047]}>
                      Failed to fetch data from the external source.

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

                      The only valid value is `"remote_request_failed"`.
                    </Prop>
                  </Prop.List>
                </Tab>

                <Tab name="AppError">
                  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.

                  <Prop.List>
                    <Prop name="status" required type="string" sourceLineNumbers={[54]}>
                      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.

                      The only valid value is `"app_error"`.
                    </Prop>

                    <Prop name="message" type="string" sourceLineNumbers={[58]}>
                      Optional message explaining the error.
                    </Prop>
                  </Prop.List>
                </Tab>
              </Tabs>
            </Tab>
          </Tabs>
        </Prop>

        <Prop name="renderSelectionUi" required type="function" sourceLineNumbers={[221]}>
          Renders a user interface for selecting and configuring data from your external sources.

          <Prop.Extras>
            **Example: Rendering a data selection UI**

            ```ts
            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);
              }
            }
            ```
          </Prop.Extras>

          **Parameters**

          <Prop.List>
            <Prop name="request" required type="RenderSelectionUiRequest" sourceLineNumbers={[221]}>
              Configuration and callbacks for the data selection UI.

              <PillAccordion defaultExpanded={false} title={<>Properties of <strong>request</strong></>}>
                <Prop.List>
                  <Prop name="invocationContext" required type="InvocationContext" sourceLineNumbers={[1066]}>
                    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.

                    <Tabs>
                      <Tab name="DataSelectionInvocationContext">
                        InvocationContext indicating initial data selection flow or edit of existing data.

                        <Prop.List>
                          <Prop name="reason" required type="string" sourceLineNumbers={[268]}>
                            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.

                            The only valid value is `"data_selection"`.
                          </Prop>

                          <Prop name="dataSourceRef" type="DataSourceRef" sourceLineNumbers={[272]}>
                            If dataSourceRef is provided, this is an edit of existing data flow and UI should be pre-populated.

                            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
                              <Prop.List>
                                <Prop name="source" required type="string" sourceLineNumbers={[309]}>
                                  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
                                </Prop>

                                <Prop name="title" type="string" sourceLineNumbers={[318]}>
                                  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
                                </Prop>
                              </Prop.List>
                            </PillAccordion>
                          </Prop>
                        </Prop.List>
                      </Tab>

                      <Tab name="OutdatedSourceRefInvocationContext">
                        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.

                        <Prop.List>
                          <Prop name="reason" required type="string" sourceLineNumbers={[1007]}>
                            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.

                            The only valid value is `"outdated_source_ref"`.
                          </Prop>

                          <Prop name="dataSourceRef" type="DataSourceRef" sourceLineNumbers={[1011]}>
                            The outdated data source reference that caused the error during refresh.

                            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
                              <Prop.List>
                                <Prop name="source" required type="string" sourceLineNumbers={[309]}>
                                  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
                                </Prop>

                                <Prop name="title" type="string" sourceLineNumbers={[318]}>
                                  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
                                </Prop>
                              </Prop.List>
                            </PillAccordion>
                          </Prop>
                        </Prop.List>
                      </Tab>

                      <Tab name="AppErrorInvocationContext">
                        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.

                        <Prop.List>
                          <Prop name="reason" required type="string" sourceLineNumbers={[75]}>
                            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.

                            The only valid value is `"app_error"`.
                          </Prop>

                          <Prop name="dataSourceRef" type="DataSourceRef" sourceLineNumbers={[79]}>
                            The data source reference that caused the error during refresh.

                            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
                              <Prop.List>
                                <Prop name="source" required type="string" sourceLineNumbers={[309]}>
                                  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
                                </Prop>

                                <Prop name="title" type="string" sourceLineNumbers={[318]}>
                                  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
                                </Prop>
                              </Prop.List>
                            </PillAccordion>
                          </Prop>

                          <Prop name="message" type="string" sourceLineNumbers={[83]}>
                            The error message to display to the user.
                          </Prop>
                        </Prop.List>
                      </Tab>
                    </Tabs>
                  </Prop>

                  <Prop name="limit" required type="DataTableLimit" sourceLineNumbers={[1074]}>
                    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.

                    <PillAccordion defaultExpanded={false} title={<>Properties of <strong>limit</strong></>}>
                      <Prop.List>
                        <Prop name="row" required type="number" sourceLineNumbers={[425]}>
                          The maximum number of rows allowed.

                          Your app should ensure data does not exceed this limit.
                        </Prop>

                        <Prop name="column" required type="number" sourceLineNumbers={[431]}>
                          The maximum number of columns allowed.

                          Your app should ensure data does not exceed this limit.
                        </Prop>
                      </Prop.List>
                    </PillAccordion>
                  </Prop>

                  <Prop name="updateDataRef" required type="function" sourceLineNumbers={[1093]}>
                    Callback to preview selected data before finalizing import.

                    Call this function when the user selects data to:

                    1. Show a preview of the selected data to the user
                    2. 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.

                    <Prop.Extras>
                      **Throws**

                      Will throw CanvaError('bad\_request') if

                      1. DataSourceRef.source exceeds 5kb.
                      2. DataSourceRef.title exceeds 255 characters.
                      3. GetDataTableCompleted.dataTable exceeds DataTableLimit or contains invalid data.
                    </Prop.Extras>

                    **Parameters**

                    <Prop.List>
                      <Prop name="dataSourceRef" required type="DataSourceRef" sourceLineNumbers={[1093]}>
                        Reference object identifying the selected data

                        <PillAccordion defaultExpanded={false} title={<>Properties of <strong>dataSourceRef</strong></>}>
                          <Prop.List>
                            <Prop name="source" required type="string" sourceLineNumbers={[309]}>
                              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
                            </Prop>

                            <Prop name="title" type="string" sourceLineNumbers={[318]}>
                              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
                            </Prop>
                          </Prop.List>
                        </PillAccordion>
                      </Prop>
                    </Prop.List>

                    **Returns**

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

                    <Tabs>
                      <Tab name="UpdateDataRefCompleted">
                        Successful result from the RenderSelectionUiRequest.updateDataRef callback.

                        <Prop.List>
                          <Prop name="status" required type="string" sourceLineNumbers={[1191]}>
                            The data selection was successful and can be previewed.

                            The only valid value is `"completed"`.
                          </Prop>
                        </Prop.List>
                      </Tab>

                      <Tab name="GetDataTableError">
                        Error results that can be returned from `getDataTable` method.

                        <Tabs>
                          <Tab name="OutdatedSourceRefError">
                            GetDataTableError indicating the data source reference is no longer valid.
                            This will trigger a re-selection flow for the user.

                            <Prop.List>
                              <Prop name="status" required type="string" sourceLineNumbers={[988]}>
                                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.

                                The only valid value is `"outdated_source_ref"`.
                              </Prop>
                            </Prop.List>
                          </Tab>

                          <Tab name="RemoteRequestFailedError">
                            GetDataTableError indicating failure to fetch data from the external source.
                            Typically due to network issues or API failures.

                            <Prop.List>
                              <Prop name="status" required type="string" sourceLineNumbers={[1047]}>
                                Failed to fetch data from the external source.

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

                                The only valid value is `"remote_request_failed"`.
                              </Prop>
                            </Prop.List>
                          </Tab>

                          <Tab name="AppError">
                            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.

                            <Prop.List>
                              <Prop name="status" required type="string" sourceLineNumbers={[54]}>
                                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.

                                The only valid value is `"app_error"`.
                              </Prop>

                              <Prop name="message" type="string" sourceLineNumbers={[58]}>
                                Optional message explaining the error.
                              </Prop>
                            </Prop.List>
                          </Tab>
                        </Tabs>
                      </Tab>
                    </Tabs>
                  </Prop>
                </Prop.List>
              </PillAccordion>
            </Prop>
          </Prop.List>

          **Returns**

          `void`
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Returns

`void`