Creating tables

Apps can add tables to a user's design. These tables are a type of native element, which means users can manipulate them as they would any other kind of element.

Features

In addition to creating tables, apps can:

• Set the text content of table cells.
• Set the background color of table cells.
• Merge table cells.

How to create a table

Step 1: Enable the required permissions

In the Developer Portal, enable the canva:design:content:write permission. In the future, the Apps SDK will throw an error if the required permissions are not enabled. To learn more, see Configuring permissions.

Step 2: Create a table

At their most basic, tables are plain JavaScript objects. These objects have rows, the rows have columns, and the columns have cells. The cells can contain content and have background colors.

The following code snippet contains an example of a table object that has a single row, column, and cell:

import { NativeTableElement } from "@canva/preview/design";

const element: NativeTableElement = {
  type: "TABLE",
  rows: [
    {
      cells: [
        {
          text: [
            {
              type: "TEXT",
              children: ["Hello world"],
            },
          ],
        },
      ],
    },
  ],
};

To create these objects, we recommend using the TableWrapper class in the starter kit. This class exposes methods for simplifying the creation of native table element objects and provides additional layers of validation.

To use the TableWrapper class:

1. Import the class from the utils directory:

   import { TableWrapper } from "utils/table_wrapper";

   tsx

   Copy

2. Call the create method, passing in the number of rows and columns the table should have:

   const table = TableWrapper.create(2, 2);

   tsx

   Copy

   This statement creates a table with two rows and two columns, resulting in a table of four cells.

3. Call the toElement method to convert the table into a native table element:

   const element = table.toElement();
   console.log(element); // => { type: "TABLE", rows: [ ... ]}

   tsx

   Copy

In this case, the table has four empty cells. To learn how to customize the table further, such as by adding text content within cells or setting the background color of cells, see Customizing tables.

Step 3: Add the table to the design

1. Import the addNativeElement method from the @canva/preview/design package:

   import { addNativeElement } from "@canva/preview/design";

   tsx

   Copy

2. Call the method, passing in the native table element object:

   addNativeElement(element);

   tsx

   Copy

Customizing tables

The TableWrapper class exposes methods for customizing the structure and appearance of tables. This section demonstrates how to accomplish some common requirements.

Adding rows

The addRow method adds a row to the table after the specified row:

import { addNativeElement } from "@canva/preview/design";
import { TableWrapper } from "utils/table_wrapper";

// Create a table
const table = TableWrapper.create(2, 2);

// Add a row *before* the first row
table.addRow(0);

// Add a row *after* the first row
table.addRow(1);

// Add the table to the design
const element = table.toElement();
addNativeElement(element);

A value of 0 adds a row before the first row.

Adding columns

The addColumn method adds a column to the table after the specified column:

import { addNativeElement } from "@canva/preview/design";
import { TableWrapper } from "utils/table_wrapper";

// Create a table
const table = TableWrapper.create(2, 2);

// Add a column *before* the first column
table.addColumn(0);

// Add a column *after* the first column
table.addColumn(1);

// Add the table to the design
const element = table.toElement();
addNativeElement(element);

A value of 0 adds a column before the first column.

Setting cell content

You can use the setCellDetails method to set the text content of the specified cell:

import { addNativeElement } from "@canva/preview/design";
import { TableWrapper } from "utils/table_wrapper";

// Create a table
const table = TableWrapper.create(2, 2);

// Set the text content of the first cell
table.setCellDetails(1, 1, {
  text: {
    type: "TEXT",
    children: ["Hello world"],
  },
});

// Add the table to the design
const element = table.toElement();
addNativeElement(element);

The first two arguments are the row and column number of the cell. These number start from 1, not 0.

Setting cell background colors

You can use the setCellDetails method to set the background color of the specified cell:

import { addNativeElement } from "@canva/preview/design";
import { TableWrapper } from "utils/table_wrapper";

// Create a table
const table = TableWrapper.create(2, 2);

// Set the background color of the first cell
table.setCellDetails(1, 1, {
  fill: {
    color: "#ff0099",
  },
});

// Add the table to the design
const element = table.toElement();
addNativeElement(element);

The first two arguments are the row and column number of the cell. These number start from 1, not 0.

Merging rows

You can use the setCellDetails method to set the row span of the cell, merging the specified number of rows:

import { addNativeElement } from "@canva/preview/design";
import { TableWrapper } from "utils/table_wrapper";

// Create a table
const table = TableWrapper.create(2, 2);

// Merge two rows
table.setCellDetails(1, 1, {
  rowSpan: 2,
});

// Add the table to the design
const element = table.toElement();
addNativeElement(element);

The first two arguments are the row and column number of the cell. These number start from 1, not 0.

Merging columns

You can use the setCellDetails method to set the col span of the cell, merging the specified number of columns:

import { addNativeElement } from "@canva/preview/design";
import { TableWrapper } from "utils/table_wrapper";

// Create a table
const table = TableWrapper.create(2, 2);

// Merge two columns
table.setCellDetails(1, 1, {
  colSpan: 2,
});

// Add the table to the design
const element = table.toElement();
addNativeElement(element);

The first two arguments are the row and column number of the cell. These number start from 1, not 0.

Getting cell details

Use the getCellDetails to get the details of the specified cell, such as its text content:

import { TableWrapper } from "utils/table_wrapper";

// Create a table
const table = TableWrapper.create(2, 2);

// Get the details of the first cell
const cell = table.getCellDetails(1, 1);
console.log(cell);

The first two arguments are the row and column number of the cell. These number start from 1, not 0.

Known limitations

• Tables can't exist within app elements.
• Tables can't exist within group elements.
• Tables can't be dragged and dropped into a design.
• Apps can't set the borders of tables.
• A single table can't have more than 225 cells.

Code sample

import { Button, Rows } from "@canva/app-ui-kit";
import { addNativeElement } from "@canva/preview/design";
import * as React from "react";
import * as styles from "styles/components.css";
import { TableWrapper } from "utils/table_wrapper";

export function App() {
  function handleClick() {
    const table = TableWrapper.create(2, 2);
    const element = table.toElement();
    addNativeElement(element);
  }

  return (
    <div className={styles.scrollContainer}>
      <Rows spacing="1u">
        <Button variant="primary" onClick={handleClick}>
          Add table to design
        </Button>
      </Rows>
    </div>
  );
}