> ## 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/)