The Data Model: Rows & Columns

TableCrafter treats every data source as a list of records: each record becomes a row, and the keys of the first record become the columns. This page explains exactly how a source is mapped, how headers are generated, and how to point at nested data.

The core rule: a list of objects

Regardless of where the data comes from, TableCrafter normalizes it into a single shape before building the table: an array where every element is an object (an associative array of key => value pairs). That mapping is fixed:

• Each element of the array becomes one <tr> row.
• Each key inside a record becomes one column. The column set is auto-discovered from the keys of the first record in the list.
• Each value is placed in the cell for its key, then passed through a smart value renderer (links, emails, dates, booleans, images, tags).

So a source like this:

[
  { "name": "Acme Co", "plan": "Pro", "seats": 12 },
  { "name": "Globex", "plan": "Team", "seats": 5 }
]

renders a three-column table (name, plan, seats) with two rows. The minimal shortcode is just the source URL:

[tablecrafter source="https://example.com/customers.json"]

How each source type maps to rows

TableCrafter accepts several source formats. All of them are converted to the same "list of objects" model described above.

How headers (column labels) are generated

The raw key becomes the column label after a light formatting pass: underscores are replaced with spaces and the result is title-cased. So first_name renders as the header First Name and seats renders as Seats.

Each header cell is output as a sortable, keyboard-focusable element:

<th class="tc-sortable" tabindex="0" aria-sort="none" data-field="first_name">First Name</th>

The original key is preserved in data-field so sorting, filtering, and value lookup always operate on the real key rather than the display label. Body cells also carry the label in data-tc-label, which the responsive card/stacked view uses to label each value on small screens.

Renaming a header (aliasing)

To override the auto-generated label, use a key:Alias pair inside the include attribute. The part before the colon must match the real key; the part after is shown as the header.

[tablecrafter source="…/customers.json"
  include="name:Company, plan:Subscription, seats:Licenses"]

This both selects the columns and relabels them, producing headers Company, Subscription, and Licenses.

Choosing which columns appear

By default every key in the first record becomes a column. Two attributes let you narrow that set. They are applied in order: include first (which also sets column order), then exclude.

Example: show only three fields, in a specific order, sorted by seat count, hiding an internal id:

[tablecrafter source="…/customers.json"
  include="name, plan, seats"
  exclude="internal_id"
  sort="seats:desc"]

Flat vs. nested data: the root attribute

TableCrafter can only turn an array into rows. Many JSON APIs wrap their list inside an envelope object, for example:

{
  "status": "ok",
  "results": {
    "customers": [
      { "name": "Acme Co", "seats": 12 }
    ]
  }
}

Point at the nested list with a dot-delimited path in root. TableCrafter walks each segment in turn before mapping rows:

[tablecrafter source="…/api.json" root="results.customers"]

If any segment of the path does not exist, the table fails with a clear "Key not found in data structure" error (shown only to administrators), so a wrong path is easy to spot. The same dot-path logic runs identically on the server (first render) and in the browser (auto-refresh), so a single root value covers both.

Nested values inside a cell

A column value does not have to be a simple string. When a cell value is itself an array or object, TableCrafter flattens it for display rather than dropping it:

• Indexed arrays (e.g. a list of tags) render as a tc-tag-list of tc-tag chips, capped at 10 items with a +N more chip beyond that.
• Associative arrays / objects render a single representative tc-tag rather than dumping raw JSON.
• Booleans become a tc-badge tc-yes / tc-badge tc-no pill ("Yes" / "No").

For Airtable specifically, nested field values are flattened at the source: attachment arrays collapse to the first file URL, linked-record arrays join their record ids with commas, and other arrays join with commas. The result is a clean, single-value cell.

Where this happens, and verifying it

You configure all of the above through the shortcode (or the matching Gutenberg block / Elementor widget). To work hands-on, open WP Admin → TableCrafter to build a source, then drop the generated [tablecrafter] shortcode into any post or page.

When something does not map the way you expect, administrators see a TableCrafter Setup Guide error block in place of the table. Its troubleshooting checklist mirrors this page: confirm the source returns a list, check the root path, and confirm the data is a list of objects (rows) rather than a single value.

Next steps

Once your data is mapping cleanly to rows and columns, continue with data-sources.html for the full details of connecting JSON, CSV, Google Sheets, and Airtable, or jump to shortcode-reference.html for every attribute the [tablecrafter] shortcode accepts.