> ## 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.
# Creating tables
How to add tables to a user's design.
Apps can add tables to a user's design. These tables are a type of [element](https://www.canva.dev/docs/apps/elements/), which means users can manipulate them as they would any other kind of element.
NOTE: If you want to bring external data into your designs or keep it in sync, we recommend you use the [Data Connector Intent](https://www.canva.dev/docs/apps/intents/data-connector/) instead of the Tables API. The Tables API is for programmatically managing table data and structure, not for powering in-design data workflows. To discuss special circumstances, contact [Developer support](https://canva-external.atlassian.net/servicedesk/customer/portal/2/group/2).
## 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 Canva Developers SDK will throw an error if the required permissions aren't enabled. To learn more, see [Permissions](https://www.canva.dev/docs/apps/configuring-intents-permissions/).
### Step 2: Create a table
At their most basic, tables are plain JavaScript objects. These objects have rows, and the rows have cells. The cells can contain content and have attributes like background color.
The following code snippet contains an example of a table object that has a single row and cell:
```tsx
import { TableElement } from "@canva/design";
const element: TableElement = {
type: "table",
rows: [
{
cells: [
{
type: "string",
value: "Hello world",
},
],
},
],
};
```
To create these objects, we recommend using the `useTable` hook from the `@canva/app-hooks` package. This hook provides a reactive way to create and manage table state with built-in validation.
To use the `useTable` hook:
1. Import the hook:
```tsx
import { useTable } from "@canva/app-hooks";
```
2. Call the hook with an initial table state, specifying the number of rows and columns:
```tsx
const tableState = useTable({ rowCount: 2, columnCount: 2 });
```
This creates a reactive table state with two rows and two columns, resulting in a table of four cells.
3. Call the `build` method to convert the table state into a table element:
```tsx
const element = tableState.build();
console.log(element); // => { type: "table", rows: [ ... ]}
```
In this case, the table has four empty cells. The `tableState` object is reactive, so you can modify properties like `rowCount` and `columnCount` directly, and these changes will automatically be reflected. 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](https://www.canva.dev/#customizing-tables).
### Step 3: Add the table to the design
Apps can add table elements to a design by calling either of the following methods:
* `addElementAtPoint`
* `addElementAtCursor`
Both methods add an element to the user's design, but:
* `addElementAtPoint` only works in [design types](https://www.canva.dev/docs/apps/designs/#design-types) that support absolute positions (fixed designs), which is all design types except for Canva Docs.
* `addElementAtCursor` only works in responsive design types that contain streams of text (currently Canva docs only).
Where possible, apps should determine the context in which the app is running and either call the compatible method or make it obvious when functionality isn't available:
```tsx
import { Button, Rows } from "@canva/app-ui-kit";
import { addElementAtCursor, addElementAtPoint } from "@canva/design";
import { useFeatureSupport, useTable } from "@canva/app-hooks";
import * as styles from "styles/components.css";
export const App = () => {
const isSupported = useFeatureSupport();
const tableState = useTable({ rowCount: 2, columnCount: 2 });
function handleAddElementAtPoint() {
if (!isSupported(addElementAtPoint)) {
return;
}
const element = tableState.build();
addElementAtPoint(element);
}
function handleAddElementAtCursor() {
if (!isSupported(addElementAtCursor)) {
return;
}
const element = tableState.build();
addElementAtCursor(element);
}
return (
);
};
```
To learn more, see [Feature support](https://www.canva.dev/docs/apps/feature-support/).
## Customizing tables
The `useTable` hook returns a reactive table state object that you can manipulate directly to customize the structure and appearance of tables. This section demonstrates how to accomplish some common requirements.
### Adding rows
You can add rows to a table by modifying the `rowCount` property of the table state:
```tsx
import { addElementAtPoint } from "@canva/design";
import { useTable } from "@canva/app-hooks";
// Create a table with 2 rows and 2 columns
const tableState = useTable({ rowCount: 2, columnCount: 2 });
// Add more rows by updating rowCount
tableState.rowCount = 4; // Now the table has 4 rows
// Add the table to the design
const element = tableState.build();
addElementAtPoint(element);
```
The table will automatically adjust to accommodate the new number of rows.
### Adding columns
You can add columns to a table by modifying the `columnCount` property of the table state:
```tsx
import { addElementAtPoint } from "@canva/design";
import { useTable } from "@canva/app-hooks";
// Create a table with 2 rows and 2 columns
const tableState = useTable({ rowCount: 2, columnCount: 2 });
// Add more columns by updating columnCount
tableState.columnCount = 4; // Now the table has 4 columns
// Add the table to the design
const element = tableState.build();
addElementAtPoint(element);
```
The table will automatically adjust to accommodate the new number of columns.
### Setting cell content
You can set the text content of specific cells by adding cell customizations to the `cells` array:
```tsx
import { addElementAtPoint } from "@canva/design";
import { useTable } from "@canva/app-hooks";
// Create a table with 2 rows and 2 columns
const tableState = useTable({
rowCount: 2,
columnCount: 2,
cells: [
{
rowPos: 1,
columnPos: 1,
text: "Hello world",
},
],
});
// Add the table to the design
const element = tableState.build();
addElementAtPoint(element);
```
The `rowPos` and `columnPos` properties specify the position of the cell. These numbers start from `1`, not `0`. You can also modify the `cells` array after initialization by assigning a new array to `tableState.cells`.
### Setting cell background colors
You can set the background color of specific cells by adding cell customizations with the `fillColor` property:
```tsx
import { addElementAtPoint } from "@canva/design";
import { useTable } from "@canva/app-hooks";
// Create a table with 2 rows and 2 columns
const tableState = useTable({
rowCount: 2,
columnCount: 2,
cells: [
{
rowPos: 1,
columnPos: 1,
fillColor: "#ff0099",
},
],
});
// Add the table to the design
const element = tableState.build();
addElementAtPoint(element);
```
The `rowPos` and `columnPos` properties specify the position of the cell. These numbers start from `1`, not `0`.
### Merging rows
You can merge rows by setting the `rowSpan` property on a cell customization:
```tsx
import { addElementAtPoint } from "@canva/design";
import { useTable } from "@canva/app-hooks";
// Create a table with 2 rows and 2 columns
const tableState = useTable({
rowCount: 2,
columnCount: 2,
cells: [
{
rowPos: 1,
columnPos: 1,
rowSpan: 2,
},
],
});
// Add the table to the design
const element = tableState.build();
addElementAtPoint(element);
```
The `rowPos` and `columnPos` properties specify the position of the cell. These numbers start from `1`, not `0`.
### Merging columns
You can merge columns by setting the `colSpan` property on a cell customization:
```tsx
import { addElementAtPoint } from "@canva/design";
import { useTable } from "@canva/app-hooks";
// Create a table with 2 rows and 2 columns
const tableState = useTable({
rowCount: 2,
columnCount: 2,
cells: [
{
rowPos: 1,
columnPos: 1,
colSpan: 2,
},
],
});
// Add the table to the design
const element = tableState.build();
addElementAtPoint(element);
```
The `rowPos` and `columnPos` properties specify the position of the cell. These numbers start from `1`, not `0`.
### Accessing cell customizations
You can access the cell customizations through the `cells` array property of the table state:
```tsx
import { useTable } from "@canva/app-hooks";
// Create a table with cell customizations
const tableState = useTable({
rowCount: 2,
columnCount: 2,
cells: [
{
rowPos: 1,
columnPos: 1,
text: "Hello world",
fillColor: "#ff0099",
},
],
});
// Access the cells array
console.log(tableState.cells);
// => [{ rowPos: 1, columnPos: 1, text: "Hello world", fillColor: "#ff0099" }]
// Find a specific cell by position
const cell = tableState.cells?.find(
(c) => c.rowPos === 1 && c.columnPos === 1
);
console.log(cell);
```
The `cells` array contains all the customizations you've defined for specific cells.
## Known limitations
* Tables can't exist within [app elements](https://www.canva.dev/docs/apps/creating-app-elements/).
* Tables can't exist within [group elements](https://www.canva.dev/docs/apps/grouping-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.
## API reference
* [`addElementAtCursor`](https://www.canva.dev/docs/apps/api/latest/design-add-element-at-cursor/)
* [`addElementAtPoint`](https://www.canva.dev/docs/apps/api/latest/design-add-element-at-point/)