Work with tables using the PowerPoint JavaScript API

Create PowerPoint tables in your add-in and control values, formatting, sizing, and merged areas by using the PowerPoint JavaScript API.

Use this article when you want to generate tables programmatically at creation time. After you create a table, you can update cell text, but not formatting or table structure.

Create an empty table

To create an empty table, call the ShapeCollection.addTable() method and specify how many rows and columns the table needs. The following code sample shows how to create a table with 3 rows and 4 columns.

await PowerPoint.run(async (context) => {
    const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;

    // Add a table (which is a type of Shape).
    const shape = shapes.addTable(3, 4);
    await context.sync();
});

The previous sample doesn't specify any options, so the table defaults to formatting provided by PowerPoint. The following image shows an example of an empty table created with default formatting in PowerPoint.

Specify values

You can populate the table with string values when you create it. To do this, provide a 2-dimensional array of values in the TableAddOptions object. The following code sample creates a table with string values from "1" to "12". Note the following:

• You must specify an empty cell as an empty string "". If a value is undefined or missing, addTable throws an error.
• The outer array contains a list of rows. Each row is an inner array containing a list of string cell values.
• The function named insertTableOnCurrentSlide is used in other samples in this article.

async function run() {
    const options: PowerPoint.TableAddOptions = {
        values: [
            ["1", "2", "", "4"], // Cell 3 is blank.
            ["5", "6", "7", "8"],
            ["9", "10", "11", "12"]
        ],
    };

    await insertTableOnCurrentSlide(3, 4, options);
}

async function insertTableOnCurrentSlide(rowCount: number, columnCount: number, options: PowerPoint.TableAddOptions) {
    await PowerPoint.run(async (context) => {
        const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;

        // Add a table (which is a type of Shape).
        const shape = shapes.addTable(rowCount, columnCount, options);
        await context.sync();
    });
}

The previous sample creates a table with values as shown in the following image.

Specify cell formatting

You can specify cell formatting when you create a table, including border style, fill style, font style, horizontal alignment, indent level, and vertical alignment. Use the TableCellProperties object to specify these formats.

Uniform cell formatting

Uniform cell formatting applies to the entire table. For example, if you set the uniform font color to white, all table cells use the white font. Use uniform cell formatting to control the default formatting you want on the entire table.

Set uniform cell formatting for the entire table by using the TableAddOptions.uniformCellProperties property. The following code sample shows how to set all table cells to dark slate blue fill color and bold white font.

const rowCount = 3;
const columnCount = 4;
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "2", "", "4"],
        ["5", "6", "7", "8"],
        ["9", "10", "11", "12"]
    ],
    uniformCellProperties: {
        fill: { color: "darkslateblue" },
        font: { bold: true, color: "white" }
    }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

The previous sample creates a table as shown in the following image.

Specific cell formatting

Specific cell formatting applies to individual cells and overrides the uniform cell formatting, if any. Set individual cell formatting by using the TableAddOptions.specificCellProperties property. The following code sample shows how to set the fill color to black for the cell at row 1, column 1.

Note that specificCellProperties must be a 2D array that exactly matches the table size. The sample first creates the entire empty 2D array of objects. Then it sets the specific cell format at row 1, column 1, after the options object is created.

const rowCount = 3;
const columnCount = 4;
const specificCellProperties = createCellArray(rowCount, columnCount);
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "2", "", "4"],
        ["5", "6", "7", "8"],
        ["9", "10", "11", "12"]
    ],
    uniformCellProperties: {
        fill: { color: "darkslateblue" },
        font: { bold: true, color: "white" }
    },
    specificCellProperties // Array values are empty objects at this point.
};
// Set fill color for specific cell at row 1, column 1.
options.specificCellProperties[1][1] = {
    fill: { color: "black" }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

// Helper function to create a 2D array filled with empty and distinct objects.
function createCellArray(rowCount: number, columnCount: number): PowerPoint.TableCellProperties[][] {
    // Using Array.from() with a factory callback ensures each cell gets its own object reference.
    return Array.from({ length: rowCount }, () => Array.from({ length: columnCount }, () => ({})));
}

The previous sample creates a table with a specific format applied to the cell in row 1, column 1 as shown in the following image.

The previous sample uses the font property which is of type FontProperties. The font property allows you to specify many properties, such as bold, italic, name, color, and more. The following code sample shows how to specify multiple properties for a font for a cell.

options.specificCellProperties[1][1] = {
    font: {
        color: "orange",
        name: "Arial",
        size: 50,
        allCaps: true,
        italic: true
    }
};

You can also specify a fill property which is of type FillProperties. The fill property can specify a color and the transparency percentage. The following code sample shows how to create a fill for all table cells using the color "dark red" and a 50% transparency.

uniformCellProperties: {
    fill: {
        color: "darkred",
        transparency: 0.5
    }
}

Borders

Use the TableCellProperties.borders object to define borders for cells in the table. The following code sample shows how to set a red border with weight 3 for the cell at row 1, column 1.

const columnCount = 3;
const rowCount = 3;
const specificCellProperties = createCellArray(rowCount, columnCount); // Helper function defined earlier.
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "2", "3"],
        ["4", "5", "6"],
        ["7", "8", "9"]
    ],
    uniformCellProperties: {
        fill: {
            color: "lightcyan",
            transparency: 0.5
        },
    },
    specificCellProperties
};
options.specificCellProperties[1][1] = {
    font: {
        color: "red",
        name: "Arial",
        size: 50,
        allCaps: true,
        italic: true
    },
    borders: {
        bottom: {
            color: "red",
            weight: 3
        },
        left: {
            color: "red",
            weight: 3
        },
        right: {
            color: "red",
            weight: 3
        },
        top: {
            color: "red",
            weight: 3
        }
    }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

Horizontal and vertical alignment

Use the TableCellProperties.horizontalAlignment property to control text alignment in a cell. The following example shows how to set horizontal alignment to left, right, and center for three cells in a table. For a list of all alignment options, see the ParagraphHorizontalAlignment enum.

const rowCount = 3;
const columnCount = 3;
const specificCellProperties = createCellArray(rowCount, columnCount); // Helper function defined earlier.
const options: PowerPoint.TableAddOptions = {
    values: [
        ["Left aligned, top", "\n\n", ""],
        ["Centered", "\n\n", ""],
        ["Right aligned, bottom", "\n\n", ""]
    ],
    uniformCellProperties: {
        fill: { color: "lightblue" },
        borders: {
            bottom: {
                color: "black",
                weight: 3
            },
            left: {
                color: "black",
                weight: 3
            },
            right: {
                color: "black",
                weight: 3
            },
            top: {
                color: "black",
                weight: 3
            }
        }
    },
    specificCellProperties // Array values are empty objects at this point.
};
options.specificCellProperties[0][0] = {
    horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.left,
    verticalAlignment: PowerPoint.TextVerticalAlignment.top
};
options.specificCellProperties[1][0] = {
    horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.center,
    verticalAlignment: PowerPoint.TextVerticalAlignment.middle
};
options.specificCellProperties[2][0] = {
    horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.right,
    verticalAlignment: PowerPoint.TextVerticalAlignment.bottom
};
await insertTableOnCurrentSlide(3, 3, options);

The previous sample creates a table with left/top, centered, and right/bottom text alignment as shown in the following image.

Specify row and column widths

Specify row and column widths using the TableAddOptions.rows and TableAddOptions.columns properties. The rows property is an array of TableRowProperties that you use to set each row's rowHeight property. Similarly, the columns property is an array of TableColumnProperties you use to set each column's columnWidth property. The width or height is set in points.

PowerPoint might not honor the height or width that you set if it needs to fit the text. For example, if the text is too wide for a column, PowerPoint increases the row height so that it can wrap the text to the next line. Similarly, the column width increases if the specified size is smaller than a single character in the specified font size.

The following code example shows how to set row height and column width for a new table. Set the rows and columns properties to arrays of objects that match each count.

const columnCount = 3;
const rowCount = 3;
const options: PowerPoint.TableAddOptions = {
    values: [
        ["Width 72pt", "Width 244pt", "Width 100pt"],
        ["", "", ""],
        ["", "^\n\nHeight 200 pt\n\nv", ""]
    ],
    // Initialize columns with an array of empty objects for each column.
    columns: Array(columnCount).fill("").map(_ => ({})),
    rows: Array(rowCount).fill("").map(_ => ({})),
    uniformCellProperties: {
        fill: { color: "lightcyan" },
        horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.center,
        verticalAlignment: PowerPoint.TextVerticalAlignment.middle,
        borders: {
            bottom: {
                color: "black",
                weight: 3
            },
            left: {
                color: "black",
                weight: 3
            },
            right: {
                color: "black",
                weight: 3
            },
            top: {
                color: "black",
                weight: 3
            }
        }
    }
};
options.columns[0].columnWidth = 72;
options.columns[1].columnWidth = 244;
options.columns[2].columnWidth = 100;
options.rows[2].rowHeight = 200;
await insertTableOnCurrentSlide(rowCount, columnCount, options);

The previous sample creates a table with three custom column widths, and one custom row height, as shown in the following image.

Specify merged areas

A merged area is two or more cells combined so that they share a single value and format. In appearance, the merged area spans multiple rows or columns. Index a merged area by its upper-left table cell location (row, column) when setting its value or format. Always use the upper-left cell of the merged area to set the value and formatting. All other cells in the merged area must be empty strings with no formatting applied.

To specify a merged area, provide the upper-left location where the area starts (row, column) and the length of the area in rows and columns. The following diagram shows an example of these values for a merged area that is 3 rows by 2 columns in size. Note that merged areas can't overlap.

Use the TableAddOptions.mergedAreas property to specify one or more merged areas. The following code sample shows how to create a table with two merged areas. About the code sample, note the following points.

• The values property must only specify the value for the upper-left corner of the merged area. All other cell values in the merged area must specify empty strings ("").

• Each merged area must specify the upper-left corner location (row, column) and the length in cells of the merged area in terms of row count and column count.

const rowCount = 3;
const columnCount = 4;
// Compact syntax to create a 2D array filled with empty and distinct objects.
const specificCellProperties = Array(rowCount).fill("").map(_ => Array(columnCount).fill("").map(_ => ({})));
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "This is a merged cell", "", "4"],
        ["5", "6", "This is also a merged cell", "8"],
        ["9", "10", "", "12"]
    ],
    uniformCellProperties: {
        fill: { color: "darkslateblue" },
        font: { bold: true, color: "white" },
        borders: {
            bottom: {
                color: "black",
                weight: 3
            },
            left: {
                color: "black",
                weight: 3
            },
            right: {
                color: "black",
                weight: 3
            },
            top: {
                color: "black",
                weight: 3
            }
        }
    },
    mergedAreas: [{ rowIndex: 0, columnIndex: 1, rowCount: 1, columnCount: 2 },
    { rowIndex: 1, columnIndex: 2, rowCount: 2, columnCount: 1 }
    ],
    specificCellProperties // Array values are empty objects at this point.
};
// Set fill color for specific cell at row 1, column 1.
options.specificCellProperties[1][1] = {
    fill: { color: "black" }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

The previous sample creates a table with two merged areas as shown in the following image.

Get and set table cell values

After you create a table, you can get or set string values in the cells. This is the only part of a table you can change. You can't change borders, fonts, widths, or other cell properties. If you need to update formatting or structure, delete the table and recreate it. The following code sample shows how to find an existing table and set a new value for a cell.

await PowerPoint.run(async (context) => {
    // Load shapes.
    const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;
    shapes.load("items");
    await context.sync();
    // Find the first shape of type table.
    const shape = shapes.items.find((shape) => shape.type === PowerPoint.ShapeType.table)
    const table = shape.getTable();
    table.load();
    await context.sync();
    // Set the value of the specified table cell.
    const cell = table.getCellOrNullObject(1, 1);
    cell.text = "A new value";
});

You can also get the following read-only properties from the table.

• rowCount
• columnCount

The following sample shows how to get the table properties and log them to the console. The sample also shows how to get the merged areas in the table.

await PowerPoint.run(async (context) => {
    // Load shapes.
    const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;
    shapes.load("items");
    await context.sync();
    // Find the first shape of type table.
    const shape = shapes.items.find((shape) => shape.type === PowerPoint.ShapeType.table)
    const table = shape.getTable();
    // Load row and column counts.
    table.load("rowCount, columnCount");
    // Load the merged areas.
    const mergedAreas = table.getMergedAreas();
    mergedAreas.load("items");
    await context.sync();
    // Log the table properties.
    console.log(mergedAreas);
    console.log(table.rowCount);
    console.log(table.columnCount);
});

See also

• PowerPoint JavaScript object model in Office Add-ins
• Work with shapes using the PowerPoint JavaScript API
• Bind to shapes in a PowerPoint presentation
• PowerPoint JavaScript API reference