Working with Nested JSON

Most real-world APIs wrap their rows inside a parent object instead of returning a bare array. TableCrafter's root attribute lets you drill into that wrapper with a dot-notation path, and its value renderer automatically flattens any leftover nested objects and arrays into readable table cells.

Why you need a data path

TableCrafter expects a list of objects — an array where each element becomes one table row and each key becomes a column. A clean endpoint returns exactly that:

[
  { "sku": "PRD-001", "product_name": "Wireless Headphones", "price": 99.99 },
  { "sku": "PRD-002", "product_name": "Ergonomic Office Chair", "price": 249.50 }
]

But many APIs nest that array under one or more parent keys, alongside metadata like paging or status:

{
  "status": "ok",
  "data": {
    "results": [
      { "sku": "PRD-001", "product_name": "Wireless Headphones", "price": 99.99 },
      { "sku": "PRD-002", "product_name": "Ergonomic Office Chair", "price": 249.50 }
    ]
  }
}

Point TableCrafter straight at this URL without a path and it sees a single object at the top, not a list of rows. The root attribute tells it where the row array actually lives.

Selecting the data path with root

Set root to a dot-separated path of the keys leading to your row array. TableCrafter splits the value on each . and walks the structure one segment at a time. For the example above, the array lives at data → results:

[tablecrafter source="https://api.example.com/catalog" root="data.results"]

Each segment must match a key exactly — the lookup is case-sensitive and uses literal key names, so use data.results, never data[results] or $.data.results. There is no array-index or wildcard syntax; root resolves keys only and the final segment must point at the array of rows (or at a single object, which is treated as a one-row table).

The root attribute at a glance

Configuring the path in the admin generator

You do not have to hand-write the shortcode. Open WP Admin → TableCrafter to reach the dashboard and shortcode generator:

1. Paste your endpoint into the Data Source URL field.
2. In the Data Root (Optional) field (placeholder data.items), enter your dot-notation path, for example data.results.
3. Use the live preview to confirm rows appear, then copy the generated [tablecrafter] shortcode.

The same control exists in the other integration methods, so the underlying root value is identical everywhere:

How flattening into columns works

Once root resolves to your array, TableCrafter builds the column set from the keys of the first row, then renders every cell through its value renderer. The renderer flattens nested structures so a column never spills raw JSON into the page:

• Scalar values (strings, numbers) render as text. ISO dates like 2026-06-21 become a <time> element, email addresses become mailto: links, and image/HTTP URLs become images or links.
• Booleans render as a badge: true shows Yes via <span class="tc-badge tc-yes"> and false shows <span class="tc-badge tc-no">.
• Plain (indexed) arrays — such as a tags list — render as a chip row: a <div class="tc-tag-list"> wrapper containing one <span class="tc-tag"> per item. Beyond 10 items a <span class="tc-tag tc-more">+N more</span> chip is appended.
• Nested objects / associative arrays are collapsed to a single chip. The renderer looks for a friendly display key in this order — name, title, label, text, value — and shows that value; if none is present it falls back to a safe JSON string. Long values are truncated at 100 characters.

Pushing deeper instead of flattening a column

If the data you actually want to tabulate is the nested object — not the wrapper around it — extend root to point further in. Given {"company": {"departments": [ ... ]}}, use root="company.departments" so each department becomes a row rather than being squeezed into one chip.

Worked example: nested products with column control

Suppose your endpoint returns rows under data.results and each row has a verbose product_name plus a numeric price. This shortcode selects the path, keeps three columns, renames one with an alias, sorts by price descending, and turns on search and export:

[tablecrafter
  source="https://api.example.com/catalog"
  root="data.results"
  include="sku,product_name:Product,price"
  sort="price:desc"
  search="true"
  export="true"]

The key:Label form inside include (here product_name:Product) relabels the header without changing the underlying key, which is useful after flattening when raw JSON keys are not presentation-ready. Columns you omit from include are dropped; alternatively use exclude to remove specific keys while keeping the rest.

Path errors and how to fix them

When a path or structure is wrong, TableCrafter returns a precise message. Logged-in administrators see a Setup Guide helper box with the exact error; visitors see a graceful fallback instead.

How it renders under the hood

The root path is applied identically on both render paths. On first load TableCrafter resolves the path in PHP and emits a fully server-side table (great for SEO); the resolved path is also written to the container as a data-root attribute on <div class="tablecrafter-container">, where the JavaScript layer re-applies the same dot-notation traversal for live search, sorting, and auto-refresh. You configure the path once and both layers stay in sync.

Next steps

Now that your rows are flowing, fine-tune which keys appear and how they're labelled in Column Management, or connect a structured backend that pre-flattens nested fields with Using Airtable as a Data Source.