Tables

Tables display structured data in rows and columns with optional headers, styling, captions, and variable data binding.

Basic table

{
  "type": "table",
  "headers": ["Name", "Role", "Email"],
  "rows": [
    ["Alice", "Engineer", "alice@example.com"],
    ["Bob", "Designer", "bob@example.com"]
  ]
}

Properties

Property	Type	Required	Default	Description
`type`	string	Yes	—	Must be `"table"`
`id`	string	No	—	Unique identifier. Auto-generated if not provided. Max: 100 chars.
`headers`	array	No	—	Header row cells. Max: 20 cells.
`rows`	array	No	—	Data rows. Each row is an array of cells. Max: 100 rows, 20 cells per row.
`columnWidths`	array	No	—	Column width definitions. Supports fixed centimeters as numbers, percentages (`"30%"`), flexible units (`"1fr"`), and `"auto"`. Must not contain more entries than the table has columns.
`align`	string	No	`"left"`	Horizontal table alignment: `"left"`, `"center"`, or `"right"`.
`dataSource`	string	No	—	Bind to a table variable instead of inline `rows`. See Variable data binding.
`mapping`	string[]	No	—	Column keys to select from the data source. Max: 20 items.
`caption`	string	No	—	Caption text for table numbering (e.g., `"Revenue by quarter"`). Max: 500 chars.
`anchor`	string	No	—	Anchor ID for internal references (e.g., `"tab-revenue"`). Pattern: `^[a-zA-Z][a-zA-Z0-9_-]*$`. Max: 100 chars.
`invisible`	boolean	No	`false`	Hide all borders and backgrounds (borderless table).
`hideHeaders`	boolean	No	`false`	Hide the header row.
`style`	object	No	—	Inline table style override. See Table style.
`spacing`	object	No	—	Spacing override with `before` and `after` in pt (0–100).
`pagination`	object	No	—	Page-break and keep hints. See Pagination.

Cell format

Each cell in headers and rows can be either a simple string or a cell object: Simple string:

["Alice", "Engineer", "alice@example.com"]

Cell object (for alignment, an embedded image, or a form field):

[
  { "text": "Alice", "align": "left" },
  { "text": "Engineer", "align": "center" },
  { "image": { "src": "https://example.com/photo.png", "width": 40, "height": 40 } }
]

Cell object properties

Property	Type	Description
`text`	string	Cell text content. Max: 1000 chars. Supports `{{varName}}` substitution.
`image`	object	Embedded cell image (see below).
`formField`	object	One nested form field (see below).
`align`	string	Cell alignment: `"left"`, `"center"`, or `"right"`

Cell image properties

Property	Type	Description
`src`	string	Image URL. Max: 2000 chars.
`caption`	string	Alt text. Max: 200 chars.
`width`	number	Width in px (10–1000).
`height`	number	Height in px (10–1000).

When a cell contains exactly one {{varName}} reference that resolves to an image variable, the cell is automatically rendered as an image. See Variables — Image variables in table cells.

Form fields in table cells

A cell may contain one form field instead of text or an image:

{
  "formField": {
    "type": "formField",
    "name": "approval",
    "fieldType": "checkbox",
    "options": ["Approved"]
  },
  "align": "left"
}

A cell may contain text, an image, or a form field, but not more than one of these at the same time. See the complete Form Fields reference.

Column widths

Use columnWidths when specific columns need a fixed or proportional width.

{
  "type": "table",
  "headers": ["Item", "Description", "Price"],
  "columnWidths": [4, "1fr", "2fr"],
  "rows": [
    ["A-100", "Short description", "€49"],
    ["B-200", "Longer product description", "€79"]
  ]
}

Supported width values:

Value	Meaning
`4`	Fixed width in centimeters.
`"30%"`	Percentage of the available table width.
`"1fr"`, `"2fr"`	Flexible share of the remaining width.
`"auto"`	Automatic/flexible width.

Mixed layouts are supported. In [4, "1fr", "2fr"], the first column is fixed at 4cm; the remaining width is split into three shares, one for column 2 and two for column 3. If fewer widths than columns are provided, remaining columns are treated as "auto". If more widths than columns are provided, validation fails.

Variable data binding

Instead of defining rows inline, bind a table to a table variable via dataSource. Use mapping to select and reorder columns.

{
  "variables": {
    "employees": {
      "type": "table",
      "columns": ["name", "department", "email", "salary"],
      "data": [
        ["Alice", "Engineering", "alice@example.com", "$120k"],
        ["Bob", "Marketing", "bob@example.com", "$95k"]
      ]
    }
  },
  "sections": [{
    "type": "flow",
    "content": [{
      "type": "table",
      "headers": ["Name", "Department"],
      "dataSource": "employees",
      "mapping": ["name", "department"]
    }]
  }]
}

When mapping is provided, only the specified columns (matched by name against the variable’s columns) are included. Without mapping, all data columns are used as-is.

Table style

Override the default table styling inline via the style property. This has the same structure as defaults.styles.table.

{
  "type": "table",
  "headers": ["Plan", "Price"],
  "rows": [["Starter", "$9"], ["Pro", "$29"]],
  "style": {
    "borders": {
      "outer": { "width": 1, "color": "#000000", "style": "solid" },
      "inner": { "width": 0.5, "color": "#DDDDDD", "style": "solid" }
    },
    "header": {
      "backgroundColor": "#1a1a2e",
      "color": "#FFFFFF",
      "fontWeight": "bold"
    },
    "rows": {
      "alternateBackgroundColor": "#F5F5F5"
    },
    "cellPadding": { "top": 6, "right": 8, "bottom": 6, "left": 8 }
  }
}

Full table style properties

borders.outer / borders.inner

Property	Type	Description
`width`	number	Border width in pt (0–10).
`color`	string	Border color in hex.
`style`	string	`"solid"`, `"dashed"`, or `"dotted"`

header

Property	Type	Description
`backgroundColor`	string	Header background color in hex.
`color`	string	Header text color in hex.
`fontSize`	number	Header font size in pt (6–72).
`fontWeight`	string	`"normal"` or `"bold"`
`fontStyle`	string	`"normal"` or `"italic"`
`align`	string	`"left"`, `"center"`, or `"right"`

rows

Property	Type	Description
`backgroundColor`	string	Row background color in hex.
`alternateBackgroundColor`	string	Alternate row background for striped tables.
`color`	string	Row text color in hex.
`fontSize`	number	Row font size in pt (6–72).
`fontWeight`	string	`"normal"` or `"bold"`
`fontStyle`	string	`"normal"` or `"italic"`
`align`	string	`"left"`, `"center"`, or `"right"`

cellPadding

Property	Type	Description
`top`	number	Top padding in pt (0–50).
`right`	number	Right padding in pt (0–50).
`bottom`	number	Bottom padding in pt (0–50).
`left`	number	Left padding in pt (0–50).

Captions and anchors

Add a caption for automatic table numbering and an anchor for cross-referencing.

{
  "sections": [{
    "type": "flow",
    "content": [
      {
        "type": "table",
        "caption": "Quarterly revenue",
        "anchor": "tab-revenue",
        "headers": ["Q1", "Q2", "Q3", "Q4"],
        "rows": [["$100k", "$120k", "$115k", "$140k"]]
      },
      { "type": "text", "text": "As shown in [Table 1](#tab-revenue), revenue grew steadily." }
    ]
  }]
}

The caption prefix (e.g., “Table”) and style are controlled by defaults.styles.tableCaption. See Defaults — Table caption style.

Defaults

Tables without an inline style inherit from defaults.styles.table:

{
  "defaults": {
    "styles": {
      "table": {
        "borders": {
          "outer": { "width": 1, "color": "#000000" },
          "inner": { "width": 0.5, "color": "#DDDDDD" }
        },
        "header": { "backgroundColor": "#F0F0F0", "fontWeight": "bold" },
        "rows": { "alternateBackgroundColor": "#FAFAFA" },
        "cellPadding": { "top": 4, "right": 6, "bottom": 4, "left": 6 }
      },
      "tableCaption": { "fontSize": 9, "fontStyle": "italic", "prefix": "Table" }
    }
  }
}

Overview

Document JSON Syntax

Tools Guides

Images

Rendering

Bulk Rendering

Projects & Documents

Templates

Styles

Reusable Blocks

Records

Tools File Management

Tools PDF Actions

Tools Document Actions

Lens (AI)

Tools Jobs

Basic table

Properties

Cell format

Cell object properties

Cell image properties

Form fields in table cells

Column widths

Variable data binding

Table style

Captions and anchors

Defaults

​Basic table

​Properties

​Cell format

​Cell object properties

​Cell image properties

​Form fields in table cells

​Column widths

​Variable data binding

​Table style

​Captions and anchors

​Defaults

Basic table

Properties

Cell format

Cell object properties

Cell image properties

Form fields in table cells

Column widths

Variable data binding

Table style

Captions and anchors

Defaults