Create a Table

Aspose.Words allows users to create tables in a document from scratch and provides several different methods for doing so. This article presents details on how to add formatted tables to your document using each method, as well as a comparison of each method at the end of the article.

Default Table Styles

The newly created table is given default values similar to those used in Microsoft Word:

Table Property Default in Aspose.Words
Border Style Single
Border Width 1/2 pt
Border Color Black
Left and Right Padding 5.4 pts
AutoFit Mode AutoFit to Window
Allow AutoFit True

Create a Table with DocumentBuilder

In Aspose.Words, users can create a table in a document using the DocumentBuilder. The basic algorithm for creating a table is as follows:

  1. Start the table with StartTable
  2. Add a cell to the table using InsertCell – this automatically starts a new row
  3. Optionally, use the CellFormat property to specify cell formatting
  4. Insert the cell content using the appropriate DocumentBuilder methods such as Writeln, InsertImage, and others
  5. Repeat steps 2-4 until the row is complete
  6. Call EndRow to end the current row
  7. Optionally, use the RowFormat property to specify row formatting
  8. Repeat steps 2-7 until the table is complete
  9. Call EndTable to finish building the table

The process of creating a table can be clearly seen in the following picture:


The following code example shows how to create a simple table using DocumentBuilder with default formatting:

The following code example shows how to create a formatted table using DocumentBuilder:

The following code example shows how to insert a nested table using DocumentBuilder:

Create a Table via DOM (Document Object Model)

You can insert tables directly into the DOM by adding a new Table node at a specific position.

Please note that immediately after the table node creation, the table itself will be completely empty, that is it does not yet contain rows and cells. To insert rows and cells into a table, add the appropriate Row and Cell child nodes to the DOM.

The following code example shows how to build a new table from scratch by adding the appropriate child nodes to the document tree:

Create a Table from HTML

Aspose.Words supports inserting content into a document from an HTML source using the InsertHtml method. The input can be a full HTML page or just a partial snippet.

Using this InsertHtml method, users can insert tables into the document via table tags like <table>, <tr>, <td>.

The following code example shows how to insert a table into a document from a string containing HTML tags:

Insert a Copy of an Existing Table

There are often times when you need to create a table based on an already existing table in a document. The easiest way to duplicate a table while retaining all formatting is to clone the Table node using the deepClone method.

The same technique can be used to add copies of an existing row or cell to a table.

The following code example shows how to duplicate a table using node constructors:

The following code example shows how to clone the last row of a table and append it to the table:

If you are looking at creating tables in a document that grow dynamically with each record from your data source, then the above method is not advised. Instead, the desired output is more easily achieved by using Mail merge with regions. You can learn more about this technique in the Mail Merge with Regions section.

Compare Ways to Create a Table

Aspose.Words provides several methods to create new tables in a document. Each method has its own advantages and disadvantages, so the choice of which to use often depends on the specific situation.

Let’s take a closer look at these ways of creating tables and compare their pros and cons:

Method Advantages Disadvantages
Via DocumentBuilder The standard method for inserting tables and other document content Sometimes difficult to create many varieties of tables at the same time with the same builder instance
Via DOM Fits in better with surrounding code that creates and inserts nodes directly into the DOM without using a DocumentBuilder The table is created “empty”: before performing most operations, you must call EnsureMinimum to create any missing child nodes
From HTML Can create a new table from HTML source using tags like <table>, <tr>, <td> Not all possible Microsoft Word table formats can be applied to HTML
Cloning an existing table You can create a copy of an existing table while retaining all row and cell formatting The appropriate child nodes must be removed before the table is ready for use