> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/create-workflow/custom-table-renderer.md).

# Configure Inputs with CustomTableRenderer

Use the CustomTableRenderer field to let developers review and edit a list of records, including nested child records, as an inline-editable table in a Workflow form.

Many APIs return several records in one response, such as a list of repositories, security groups, or services. Other workflow inputs handle that response one value at a time, for example, `SelectFieldFromApi` picks a single item from it, and a plain array input renders each record as a stack of form fields that you cannot prefill from an API. Developers end up editing one record at a time and running the workflow once for each record.

`CustomTableRenderer` renders the whole list as an editable table inside the Workflow form. The field can load rows from an API, and lets developers search, sort, add, edit, duplicate, and delete rows in place. When the developer submits the form, the workflow receives every edit, addition, and deletion together as JSON, in a single workflow execution.

![A Workflow form step with a Users table that lists users, their details, and an expand control for each user's orders](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-f0cbd55806fb5fafe2e39dd2d8e368a6496e269a%2Fcustom-table-renderer-overview.png?alt=media)

## When to use CustomTableRenderer

Use `CustomTableRenderer` when the input is a collection of objects that a developer has to review, compare, or change before the workflow runs.

| Input                                                                                                  | Field to use                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A single text, dropdown, button, or JSON value                                                         | [`CustomField`](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/create-workflow/custom-field.md)                                                                                    |
| A list of plain values, such as regions or tags                                                        | An [array input](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/create-workflow/flows-input.md#array-options), or `CustomField` with `fieldType: dropdown` and `multiSelect: true` |
| A list of records with several fields each, often prefilled from an API, edited and submitted together | `CustomTableRenderer`                                                                                                                                                                                                     |

***

## Before you begin

Make sure you have the following in place:

* Be familiar with [configuring workflow inputs](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/create-workflow/flows-input.md) and the `spec.parameters` structure of `workflow.yaml`.
* To load rows from an API through a backend proxy, configure a [Backend Proxy](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflows-tutorials/dynamic-picker.md#step-1-create-a-backend-proxy) first. The proxy holds the target base URL and the authorization headers. You need one only when the API is on another origin or needs authorization that the backend adds. A table that developers fill in by hand, or that the workflow pre-fills, needs no proxy.

{% hint style="info" %}
API paths in `CustomTableRenderer` use the format `proxy/<endpoint-name>/<api-path>`, the same format used by [`CustomField`](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/create-workflow/custom-field.md#before-you-begin) and the [Dynamic Workflow Picker](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflows-tutorials/dynamic-picker.md#step-2-create-the-dropdown-picker-in-workflows-form). Here `<endpoint-name>` is the proxy endpoint you declared under **Configure** → **Plugins** → **Configure Backend Proxies**.
{% endhint %}

{% hint style="warning" %}
The [Workflow Playground](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflowyaml.md#workflows-playground) does not render advanced inputs accurately. Test `CustomTableRenderer` fields in an actual workflow execution.
{% endhint %}

***

## How the configuration fits together

Every `CustomTableRenderer` property on this page follows the same model: JSON Schema defines the row data, and `ui:options` defines how the table presents it.

* **JSON Schema** (`type`, `items`, `required`, `properties`) is the data contract. It defines what a row contains, which values are valid, and the shape of the value that the workflow submits.
* **UI options** (`ui:field`, `ui:options`) are the presentation. They define where the rows come from, which columns the table displays, how each cell is edited, and which table actions are available.

Keep each column `key` in sync with a property name under `items.properties`. The table validates and submits rows from the schema, and displays only the columns you declare.

The following skeleton labels each part. Use it as a map while you work through the steps below. For the full rules that connect schema to columns, the schema-to-column type pairing, and nesting limits, go to [Configuration model](#configuration-model).

```yaml
users:                            # Property ID. Later steps read it as parameters.users
  title: Users                    # Label above the table
  type: array                     #    JSON Schema: the data contract
  items:                          #    Each array item is one table row
    type: object
    required:                     #    Fields every row must have
      - firstName
    properties:                   #    Fields a row can have
      firstName:
        type: string
        title: First name
  ui:field: CustomTableRenderer   #    UI: render this property as a table
  ui:options:
    path: proxy/test-data/users.json  # Where rows come from (optional)
    arraySelector: users              # Which part of the API response holds the rows
    columns:                          # What the table displays
      - key: firstName                # Must match a property name under items.properties
        label: First name             # Column header
        type: string                  # Cell editor
        required: true                # Checked when the developer saves the row
```

***

## Build a table step by step

Each step on this page adds one capability to the same `users` table. Step 1 gives you a complete workflow to register. The later steps change only the `users` property, so replace that property in your workflow and run it again to see the result.

| Step                                                                                         | What you add                                   |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [Step 1: Render an editable table](#step-1-render-an-editable-table)                         | A table that developers fill in by hand        |
| [Step 2: Load rows from an API](#step-2-load-rows-from-an-api)                               | Rows fetched from a JSON file or an API        |
| [Step 3: Add cell editors and validation](#step-3-add-cell-editors-and-validation)           | Checkboxes, dropdowns, date pickers, and rules |
| [Step 4: Add nested rows](#step-4-add-nested-rows)                                           | A child table of orders under each user        |
| [Step 5: Tune table behavior and labels](#step-5-tune-table-behavior-and-labels)             | Paging, actions, review view, and custom text  |
| [Step 6: Use the table data in workflow steps](#step-6-use-the-table-data-in-workflow-steps) | Values passed to actions and pipelines         |

A table gets its rows in one of three ways:

* **Manual:** Developers add and edit rows by hand, as in Step 1. The field makes no network calls, so it needs no proxy.
* **Pre-filled:** The workflow passes the rows in through its form values. The field makes no network calls, so it needs no proxy.
* **API fetch:** `ui:options.path` fetches the rows, as in Step 2. This is the only way that makes network calls. It goes through a backend proxy, or calls the API directly with `useDirectApi: true`.

However the rows arrive, Steps 3 to 5 work the same way, as the table handles cell editors, nested rows, paging, and labels in the browser.

### Step 1: Render an editable table

Start with a table that has no data source. With no `path`, the table starts empty and developers add rows by hand.

<details>

<summary>Step 1 workflow.yaml</summary>

```yaml
apiVersion: harness.io/v1
kind: Workflow
name: UserTableDemo
identifier: user_table_demo
type: service
owner: team_idp
metadata:
  description: Collects a list of users in an editable table
spec:
  parameters:
    - title: Add users by hand
      required:
        - users
      properties:
        users:
          title: Users
          type: array
          items:
            type: object
            required:
              - firstName
              - email
            properties:
              firstName:
                type: string
                title: First name
                minLength: 1
              lastName:
                type: string
                title: Last name
              email:
                type: string
                title: Email
                minLength: 1
          ui:field: CustomTableRenderer
          ui:options:
            columns:
              - key: firstName
                label: First name
                type: string
                required: true
              - key: lastName
                label: Last name
                type: string
              - key: email
                label: Email
                type: string
                required: true
  steps:
    - id: log-users
      name: Log user summary
      action: debug:log
      input:
        message: Received ${{ parameters.users.length }} users. First user is ${{ parameters.users[0].firstName }}.
```

</details>

Register the workflow, and then open it. The table displays an empty state and an **Add table row** button.

![An empty Users table with the empty-state message and the Add table row button](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-f4805032f0036ea8e66d8b531b51a9de248083a6%2Fcustom-table-renderer-empty.png?alt=media)

Click **Add table row** to insert a new row at the top of the table, already in edit mode. Fill in the cells, and then click the tick to save the row, or the cross to discard it.

### Step 2: Load rows from an API

To prefill the table, point it at an API or a hosted JSON file through a backend proxy.

1. Host the data. The following example uses a JSON file in a Git repository. Save the following content as `users-demo.json`. The same file serves every later step and the first complete example.

   ```json
   {
     "users": [
       {
         "id": 1,
         "firstName": "Alice",
         "lastName": "Rao",
         "email": "alice@example.com",
         "country": "India",
         "active": true,
         "plan": "enterprise",
         "joinedAt": "2024-03-14",
         "lastLoginAt": "2026-10-20T09:30:00Z",
         "lastSeen": 1760952600000,
         "tags": [
           "admin",
           "beta"
         ],
         "metadata": {
           "team": "payments"
         },
         "orders": [
           {
             "orderId": "ORD-1001",
             "item": "Laptop stand",
             "quantity": 1,
             "status": "shipped",
             "shipments": [
               {
                 "carrier": "BlueDart",
                 "tracking": "BD123456",
                 "events": [
                   {
                     "status": "picked",
                     "note": "Left warehouse",
                     "meta": [
                       {
                         "key": "hub",
                         "value": "Pune",
                         "details": [
                           {
                             "label": "LEVEL-5-TEST",
                             "info": "deepest"
                           }
                         ]
                       },
                       {
                         "key": "scan",
                         "value": "A1"
                       }
                     ]
                   },
                   {
                     "status": "delivered",
                     "note": "Signed by reception",
                     "meta": [
                       {
                         "key": "hub",
                         "value": "Mumbai"
                       }
                     ]
                   }
                 ]
               }
             ]
           },
           {
             "orderId": "ORD-1002",
             "item": "USB-C hub",
             "quantity": 2,
             "status": "pending",
             "shipments": []
           }
         ]
       },
       {
         "id": 2,
         "firstName": "Ben",
         "lastName": "Ortiz",
         "email": "ben@example.com",
         "country": "Spain",
         "active": false,
         "plan": "team",
         "joinedAt": "2025-01-05",
         "lastLoginAt": "2026-09-30T18:00:00Z",
         "lastSeen": 1759255200000,
         "tags": [
           "support"
         ],
         "metadata": {},
         "orders": [
           {
             "orderId": "ORD-2001",
             "item": "Monitor arm",
             "quantity": 1,
             "status": "delivered",
             "shipments": []
           }
         ]
       }
     ]
   }
   ```
2. Declare a backend proxy endpoint that points at the folder that holds the file. In IDP, go to **Configure** → **Plugins** → **Configure Backend Proxies**, add the following endpoint, and then click **Save Configuration**. Replace the placeholders with your repository details.

   ```yaml
   proxy:
     endpoints:
       /test-data:
         target: https://raw.githubusercontent.com/<org>/<repo>/<branch>
         pathRewrite:
           /api/proxy/test-data/?: /
   ```
3. Add `path` and `arraySelector` to the `users` property.

   ```yaml
   ui:field: CustomTableRenderer
   ui:options:
     path: proxy/test-data/users-demo.json
     arraySelector: users
     columns:
       - key: firstName
         label: First name
         type: string
         required: true
       - key: lastName
         label: Last name
         type: string
       - key: email
         label: Email
         type: string
         required: true
   ```

* `path` is the request path through the backend proxy.
* `arraySelector` points to the value in the response that becomes the table rows. In this file, the rows are under the `users` key. Omit `arraySelector` when the response body is itself the array. `selector` is an accepted alias.

{% hint style="info" %}
To try the table without hosting a file, use the public DummyJSON API. Declare a proxy endpoint named `dummyjson` with the target `https://dummyjson.com`, and then set `path: proxy/dummyjson/users?limit=10` and `arraySelector: users`. The `firstName`, `lastName`, and `email` columns from this page fill in from that response.
{% endhint %}

When the developer opens the step, the field fetches the rows and displays a loading skeleton until the request completes. If the step already holds row data, for example after the developer goes back to an earlier step, the table keeps that data and does not call the API again until the developer clicks **Refetch data**.

![The Users table filled with rows loaded from the users-demo.json file, with the row count and the Refetch data action in the toolbar](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-9cef09f711e0b75cfd5be493189471447b818773%2Fcustom-table-renderer-loaded.png?alt=media)

The API response does not have to be an array of objects. Go to [Supported response shapes](#supported-response-shapes) for the other formats the table accepts. To send query parameters, headers, a request body, or details of the signed-in user, go to [Request options](#request-options).

### Step 3: Add cell editors and validation

The column `type` selects the editor that appears when a developer edits a cell. Declare a typed column for each field, and declare the matching type in the schema as described in [Match schema types to column types](#match-schema-types-to-column-types).

| Column `type` | Editor                               | Grid display and submitted value                                     |
| ------------- | ------------------------------------ | -------------------------------------------------------------------- |
| `string`      | Text input                           | The text                                                             |
| `number`      | Text input that accepts only numbers | The number                                                           |
| `boolean`     | Checkbox                             | `true` or `false`                                                    |
| `select`      | Dropdown of the configured `options` | The stored `value`, not the option `label`                           |
| `date`        | Date picker                          | `yyyy-MM-dd`                                                         |
| `datetime`    | Date and time picker                 | The grid displays `yyyy-MM-dd HH:mm`. The value is an ISO timestamp. |
| `json`        | Compact text area                    | The JSON value. The content must be valid JSON.                      |

The following `users` property adds a locked number, a checkbox, a dropdown with a default, a date, two date-and-time columns, and two JSON columns, and validates the email format.

<details>

<summary>Step 3 users property</summary>

```yaml
users:
  title: Users
  type: array
  items:
    type: object
    required:
      - firstName
      - email
    properties:
      id:
        type: number
        title: Id
      firstName:
        type: string
        title: First name
        minLength: 1
      lastName:
        type:
          - string
          - "null"
        title: Last name
      email:
        type: string
        title: Email
        minLength: 1
        pattern: ^[^@\s]+@[^@\s]+$
      active:
        type: boolean
        title: Active
      plan:
        type: string
        title: Plan
        enum:
          - free
          - team
          - enterprise
      joinedAt:
        type: string
        title: Joined
        format: date
      lastLoginAt:
        type: string
        title: Last login
        format: date-time
      lastSeen:
        type: number
        title: Last seen
      tags:
        type: array
        title: Tags
        items:
          type: string
      metadata:
        type: object
        title: Metadata
  ui:field: CustomTableRenderer
  ui:options:
    path: proxy/test-data/users-demo.json
    arraySelector: users
    columns:
      - key: id
        label: Id
        type: number
        editable: false
        defaultValue: 0
      - key: firstName
        label: First name
        type: string
        required: true
        placeholder: e.g. Priya
      - key: lastName
        label: Last name
        type: string
      - key: email
        label: Email
        type: string
        required: true
        width: 240
      - key: active
        label: Active
        type: boolean
      - key: plan
        label: Plan
        type: select
        defaultValue: free
        options:
          - label: Free
            value: free
          - label: Team
            value: team
          - label: Enterprise
            value: enterprise
      - key: joinedAt
        label: Joined
        type: date
      - key: lastLoginAt
        label: Last login
        type: datetime
      - key: lastSeen
        label: Last seen
        type: datetime
        editable: false
      - key: tags
        label: Tags
        type: json
        sortable: false
      - key: metadata
        label: Metadata
        type: json
```

</details>

**Keep API-owned values read-only**

Set `editable: false` on a column for values that the API owns, such as timestamps or identifiers. Developers can read the cell but cannot change it, and that includes the rows they add: a new row leaves the cell empty. A `datetime` column also displays epoch-millisecond numbers, such as `1760952600000`, as a date and time.

Under `items.properties`:

```yaml
lastSeen:
  type: number
  title: Last seen
```

Under `ui:options.columns`:

```yaml
- key: lastSeen
  label: Last seen
  type: datetime
  editable: false
```

![A user row in edit mode with a text input, a checkbox, a Plan dropdown, and a date picker, and the tick and cross actions](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-3a62d55aa119e55356277eb4bb60051f9e93d027%2Fcustom-table-renderer-inline-edit.png?alt=media)

**Where validation rules live**

The table checks a row when the developer clicks the tick to save it. The rules come from both halves of the configuration:

| Rule                                      | Where you declare it                                                       | What happens when a value breaks it                       |
| ----------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------- |
| A cell must have a value                  | `required: true` on the column                                             | The row stays in edit mode and the cell displays an error |
| A field must exist on every row           | The field key under `items.required` in the schema                         | The row fails schema validation                           |
| A string must not be empty                | `minLength: 1` on the schema property                                      | The row fails schema validation                           |
| A string must have a set length or format | `minLength`, `maxLength`, or `pattern` on the schema property              | The row fails schema validation                           |
| A number must be within a range           | `minimum` or `maximum` on the schema property                              | The row fails schema validation                           |
| A value must come from a fixed list       | `enum` on the schema property, and the same values in the column `options` | The row fails schema validation                           |
| A value must be a number or valid JSON    | `type: number` or `type: json` on the column                               | The row stays in edit mode and the cell displays an error |
| The table must have at least one row      | `minItems: 1` on the table property, next to `type: array`                 | The form displays an error for the whole table            |

When a save fails, the row stays in edit mode, a red left border marks the row, and the error appears under each failing cell. Rows loaded from the API that do not match the schema display a red highlight, and developers can list them with the **Errors** filter. The form also validates the whole table against the schema when the developer clicks **Next**. The developer cannot continue until every active row passes, so they fix or delete each red row first.

Declare required fields on both halves: `required: true` on the column catches the empty cell while the developer edits, and `items.required` in the schema keeps rows loaded from the API honest.

{% hint style="info" %}
**New rows are checked against the schema too.**

A row that a developer adds displays red instead of green when it fails the schema, and like any failing row it stops the form at **Next**. The most common cause is a column with `editable: false` whose schema rule rejects an empty value, such as an `id` declared as `type: number`: the developer cannot fill the cell, so every new row fails. The form then displays an error such as `'Users 0 Id' must be number`. If developers add rows to the table, give that column a `defaultValue` that passes the schema, or turn off adding with `allowAdd: false`. A new row starts with the default value in the locked cell:

```yaml
- key: id
  label: Id
  type: number
  editable: false
  defaultValue: 0
```

{% endhint %}

![A user row with a red left border and the error text under the empty First name cell](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-f8b6fb9a4157cdb93fc7674bf448df4f0ea8fc14%2Fcustom-table-renderer-validation-error.png?alt=media)

{% hint style="info" %}
**Allow empty values from an API.**

Many APIs return `null` for an empty field, such as a user with no last name. A property declared as `type: string` rejects `null`, and the row fails validation. Declare both types to accept `null`:

```yaml
lastName:
  type:
    - string
    - "null"
  title: Last name
```

{% endhint %}

{% hint style="info" %}
A `select` cell displays the stored `value`, not the option `label`. Choose values that read clearly in the grid, such as `enterprise` instead of `ent-03`.
{% endhint %}

### Step 4: Add nested rows

Add a child table when each row owns a list of related records, such as the orders that belong to a user. A child table needs two changes, one in each half:

1. **In the schema**, add a property under `items.properties` that is an array of objects, with its own `properties`.
2. **In `columns`**, add a column with the same `key`, `type: nested`, and its own `columns` list.

The following snippet adds an `orders` child table to each user. The lines marked `# new` are the additions to the Step 3 property.

```yaml
users:
  title: Users
  type: array
  items:
    type: object
    required:
      - firstName
      - email
    properties:
      firstName:
        type: string
        title: First name
        minLength: 1
      email:
        type: string
        title: Email
        minLength: 1
      orders:                      # new: schema for the child table
        type: array
        title: Orders
        items:
          type: object
          required:
            - item
          properties:
            orderId:
              type: string
              title: Order Id
            item:
              type: string
              title: Item
              minLength: 1
            quantity:
              type: number
              title: Qty
              minimum: 1
            status:
              type: string
              title: Status
              enum:
                - pending
                - shipped
                - delivered
                - cancelled
  ui:field: CustomTableRenderer
  ui:options:
    path: proxy/test-data/users-demo.json
    arraySelector: users
    columns:
      - key: firstName
        label: First name
        type: string
        required: true
      - key: email
        label: Email
        type: string
        required: true
      - key: orders                # new: column for the child table
        label: Orders
        type: nested
        columns:
          - key: orderId
            label: Order Id
            type: string
          - key: item
            label: Item
            type: string
            required: true
          - key: quantity
            label: Qty
            type: number
          - key: status
            label: Status
            type: select
            options:
              - label: Pending
                value: pending
              - label: Shipped
                value: shipped
              - label: Delivered
                value: delivered
              - label: Cancelled
                value: cancelled
```

The data for each user then carries an `orders` array, for example:

```json
{
  "firstName": "Alice",
  "email": "alice@example.com",
  "orders": [
    { "orderId": "ORD-1001", "item": "Laptop stand", "quantity": 1, "status": "shipped" }
  ]
}
```

A developer clicks the chevron (>) on a user row to expand the orders table under it.

![A user row expanded to display its Orders child table, indented under the parent row, with one order expanded further to display its Shipments](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-a9c3e957b8e0d0b23efe1a2d95a70c46ee80f68f%2Fcustom-table-renderer-nested-rows.png?alt=media)

To go deeper, repeat the same two changes inside the child: add an array-of-objects property to the child schema, and add a `type: nested` column to the child `columns`. The [complete example](#complete-example) nests shipments under orders, events under shipments, key-value pairs under events, and details under the key-value pairs.

How nested tables behave:

* Each nested table supports the same inline add, edit, duplicate, delete, and undo actions as the top-level table.
* A nested table has a **+ Add** bar at the bottom that appends a new child row in edit mode.
* Each level has a darker background and a light blue left rail, so the depth is visible at a glance.
* Search, pagination, selection, and the status filter belong to the top-level table. Search also matches values inside nested rows.
* You cannot sort nested columns.
* An empty child list displays an empty state. The expand control appears when the row has children or when adding is allowed, so developers can create the first child record.
* Nesting goes up to four levels. Beyond that, expanding a row opens a JSON editor that validates the content against the `items` schema of that property. The review step displays that data as read-only JSON.

{% hint style="info" %}
Two or three levels are the easiest to scan. Use a child table only when the child records belong directly to the parent row.
{% endhint %}

### Step 5: Tune table behavior and labels

Every table action is on by default. Set an option only to change the page size or to turn off part of the experience.

```yaml
ui:options:
  path: proxy/dummyjson/users?limit={{ parameters.userLimit }}
  arraySelector: users
  pageSize: 5                # Rows per page. Developers can still pick 5, 10, 20, 50, or 100
  columns:
    # ...
```

To make the table view-only, set `readOnly: true`. The table then hides the actions column, the status filter, and the row selection checkboxes.

```yaml
ui:options:
  path: proxy/dummyjson/users?limit={{ parameters.userLimit }}
  arraySelector: users
  pageSize: 5
  readOnly: true
  columns:
    # ...
```

To let developers update existing records but not add or remove any, turn off the actions that change the row list. Lock the columns that identify a record with `editable: false`.

```yaml
ui:options:
  path: proxy/dummyjson/users?limit={{ parameters.userLimit }}
  arraySelector: users
  pageSize: 5
  allowAdd: false
  allowDelete: false
  allowDuplicate: false
  selectable: false
  columns:
    - key: id
      label: Id
      type: number
      editable: false
    - key: firstName
      label: First name
      type: string
      required: true
```

Go to [Table behavior options](#table-behavior-options) for the full list.

**Use the language of your workflow**

Use `labels` to replace the generic table text with terms that match the records, such as **Add user** instead of **Add table row**. Keys that you do not set keep their default text.

```yaml
ui:options:
  labels:
    addRow: Add user
    searchPlaceholder: Search users
    rowCount: "{{ count }} users ({{ deleted }} removed)"
    deleteConfirm: Remove this user?
```

`rowCount` and `deleteSelectedConfirm` support the `{{ count }}` placeholder, and `rowCount` also supports `{{ deleted }}`. A `rowCount` that includes `{{ deleted }}` displays it even when nothing is deleted, for example `6 users (0 removed)`. Go to [Labels](#labels) for every key and its default text.

![The Users table toolbar with the Add user button, the Search users placeholder, and a custom row count](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-a2bfa4946d9348be1e1f5661f105c2a682f30bb3%2Fcustom-table-renderer-custom-labels.png?alt=media)

### Step 6: Use the table data in workflow steps

When the developer submits the workflow, the field value is an array of row objects in the shape of the schema. Each row keeps every field it loaded with, including fields that have no column and no schema property. The table leaves out deleted rows at every nesting level, and it never includes its internal added or deleted markers. The value holds every active row, not only the rows the developer changed, so a later step that applies changes receives the full list.

For example, Ben's row from `users-demo.json` arrives with every field from the file, including the `country`, `tags`, and `lastSeen` fields that Step 4 declares no column for:

```json
[
  {
    "id": 2,
    "firstName": "Ben",
    "lastName": "Ortiz",
    "email": "ben@example.com",
    "country": "Spain",
    "active": false,
    "plan": "team",
    "joinedAt": "2025-01-05",
    "lastLoginAt": "2026-09-30T18:00:00Z",
    "lastSeen": 1759255200000,
    "tags": [
      "support"
    ],
    "metadata": {},
    "orders": [
      {
        "orderId": "ORD-2001",
        "item": "Monitor arm",
        "quantity": 1,
        "status": "delivered",
        "shipments": []
      }
    ]
  }
]
```

Read the value in later steps with `${{ parameters.<propertyId> }}`, and use index and key access to reach a single row or a nested value.

```yaml
steps:
  - id: log-summary
    name: Log user summary
    action: debug:log
    input:
      message: users=${{ parameters.users.length }} firstUser=${{ parameters.users[0].firstName }} firstOrderItem=${{ parameters.users[0].orders[0].item }}
  - id: log-table
    name: Log submitted table JSON
    action: debug:log
    input:
      message: ${{ parameters.users | dump(2) }}
```

The second step uses the Nunjucks `dump` filter, which turns the whole table into JSON text. `dump(2)` indents it by two spaces, so the log is easy to read.

![Workflow execution logs with the user count, the first user name, and the first order item](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-812a0cb46615463099d117e706eb3b8b8f738e20%2Fcustom-table-renderer-step-logs.png?alt=media)

**Pass the table to a Harness pipeline**

Pipeline variables hold strings, so convert the table to a JSON string with `dump` in the `inputset` of your [`trigger:harness-custom-pipeline`](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/create-workflow/harness-pipeline.md) step. In the pipeline, declare a variable of type **String** with the same name, such as `users_json`.

```yaml
- id: trigger
  name: Send table to pipeline
  action: trigger:harness-custom-pipeline
  input:
    url: <PIPELINE_URL>
    inputset:
      users_json: ${{ parameters.users | dump }}
    apikey: ${{ parameters.token }}
```

As each row keeps every field the API returned, the string can be large when the API returns many fields for each record. Check the size before you pass a long table, or call an API endpoint that returns fewer fields.

The pipeline reads the JSON with `<+pipeline.variables.users_json>`. The `apikey` input needs a `token` property with `ui:field: HarnessAuthToken` on the form. Go to [Example: Send the edited table to a pipeline](#example-send-the-edited-table-to-a-pipeline) for the full workflow and a pipeline that receives the table.

***

## What developers see in the table

This section describes the table from the point of view of a developer who fills in the workflow, so that you know what your configuration produces.

### Toolbar

The table has the following controls:

* **Search** filters rows as the developer types, across the visible columns and nested values. Every word in the search must match.
* **Status filter** lists all rows, newly added rows, deleted rows, or rows with errors. The new, deleted, and errors filters apply only to top-level rows.
* **Row count** displays the number of active rows. When `allowDelete` is on and deleted rows exist, it adds a deleted count, for example `12 table rows (2 deleted)`.
* **Refetch data** reloads the rows from the API after a confirmation, replaces the local edits, and clears the filter, the selection, and the expanded rows.
* **Add table row** inserts a new row at the top of the table.

Selecting a column header sorts the table in ascending order, then descending order, and then removes the sort.

![The status filter dropdown open with the All, New, Deleted, and Errors options](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-a28b0902f90bb2bca0defe220f5897285a18b18a%2Fcustom-table-renderer-status-filter.png?alt=media)

### Inline editing

The table works like a spreadsheet. There are no dialogs for adding or editing rows.

* **Edit** turns the cells of a row into editors in place. Only one row per table level is in edit mode at a time.
* The **tick** validates and saves the row. The **cross** cancels the edit and restores the original values.
* **Add** inserts a new row in edit mode, prefilled with the `defaultValue` of each column. Cancelling a new row removes it without leaving a blank row behind.
* **Duplicate** copies a row, including its nested rows, and inserts the copy directly below the original. The action is available at every table level.

### Row states

The table tracks every change on the row, so developers can confirm what changed before they submit.

| Change                                | What the developer sees                                                                       | Submitted                       |
| ------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------- |
| Row loaded from the API               | A normal row                                                                                  | Yes                             |
| Row added or duplicated               | A green highlight. If the new row fails the schema, the red highlight replaces the green one. | Yes, without the new-row marker |
| Row loaded from the API, then deleted | An orange removed state. The row action changes to **Undo delete**.                           | No                              |
| Newly added row deleted               | The row disappears immediately                                                                | No                              |
| Row that fails the schema             | A red highlight. The table does not validate deleted rows.                                    | Yes, unless the row is deleted  |
| Row in edit mode                      | A blue highlight, and a red left border when its validation fails                             | Not until it is saved           |

Bulk actions follow the active filter. With all rows or error rows listed, the selection supports **Delete selected table rows**. With new rows listed, it supports **Undo added rows**. With deleted rows listed, it supports **Undo deleted rows**.

Local edits, including added and deleted rows, stay in place when the developer leaves the step and comes back, unless the form value is replaced.

![The Users table with a green added row, an orange deleted row with the Undo delete action, and a row count that includes the deleted count](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-3ceb59e4eda25b64e1877c62398323f89c6b5053%2Fcustom-table-renderer-row-states.png?alt=media)

### Layout

The table has the following layout behaviors:

* The table scrolls horizontally when the columns do not fit, instead of squeezing the cells.
* The selection and expand columns stay pinned on the left, and the actions column stays pinned on the right.
* The top-level header stays in view during vertical scroll. Each nested table has its own horizontal scroll.

### Review step

The review step displays the field as a read-only table with the same columns, labels, and nested expand behavior, up to a depth of four. The review table truncates long cell text. The review table has no search, editing, pagination, selection, or status filter.

When `allowJsonView` is on, which is the default, a **Table** and **JSON** toggle appears above the review table. The JSON view is a read-only, syntax-highlighted, copyable view of the exact value that the workflow submits. Set `reviewDefaultView: json` to open the review on the JSON view.

![The workflow review step with the Users table in read-only mode and the Table and JSON toggle](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-3d79d9e8b5e4a204403bb551a40c1ee0f8d76b98%2Fcustom-table-renderer-review-table.png?alt=media)

![The workflow review step on the JSON view, with the submitted users array](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-ba5d6ab51e807fee4bb8c1a449f48c9a71d475e4%2Fcustom-table-renderer-review-json.png?alt=media)

***

## Complete example

### Example: Users with nested orders

The following workflow loads the `users-demo.json` file from [Step 2](#step-2-load-rows-from-an-api), nests orders, shipments, tracking events, key-value pairs, and details under each user, and logs the submitted table. Alice's first order reaches the fifth level, where the table opens a JSON editor. The workflow uses custom labels and a locked `Id` column with a default value for new rows. It expects a backend proxy endpoint named `test-data` that serves the file.

<details>

<summary>Example workflow.yaml</summary>

```yaml
apiVersion: harness.io/v1
kind: Workflow
name: Demo-Users-Orders-Table
identifier: demo_users_orders_table
type: service
owner: team_idp
metadata:
  description: Users with orders, shipments, events, meta, and details, and logs of the submitted table.
spec:
  parameters:
    - title: Users and their orders
      required:
        - users
      properties:
        users:
          title: Users
          type: array
          items:
            type: object
            required:
              - firstName
              - email
            properties:
              id:
                type: number
                title: Id
              firstName:
                type: string
                title: First name
                minLength: 1
              lastName:
                type:
                  - string
                  - "null"
                title: Last name
              email:
                type: string
                title: Email
                minLength: 1
              plan:
                type: string
                title: Plan
                enum:
                  - free
                  - team
                  - enterprise
              orders:
                type: array
                title: Orders
                items:
                  type: object
                  required:
                    - item
                  properties:
                    orderId:
                      type: string
                      title: Order Id
                    item:
                      type: string
                      title: Item
                      minLength: 1
                    quantity:
                      type: number
                      title: Qty
                      minimum: 1
                    status:
                      type: string
                      title: Status
                      enum:
                        - pending
                        - shipped
                        - delivered
                        - cancelled
                    shipments:
                      type: array
                      title: Shipments
                      items:
                        type: object
                        properties:
                          carrier:
                            type: string
                            title: Carrier
                          tracking:
                            type: string
                            title: Tracking
                          events:
                            type: array
                            title: Events
                            items:
                              type: object
                              properties:
                                status:
                                  type: string
                                  title: Status
                                note:
                                  type: string
                                  title: Note
                                meta:
                                  type: array
                                  title: Meta
                                  items:
                                    type: object
                                    properties:
                                      key:
                                        type: string
                                        title: Key
                                      value:
                                        type: string
                                        title: Value
                                      details:
                                        type: array
                                        title: Details
                                        items:
                                          type: object
                                          properties:
                                            label:
                                              type: string
                                              title: Label
                                            info:
                                              type: string
                                              title: Info
          ui:field: CustomTableRenderer
          ui:options:
            path: proxy/test-data/users-demo.json
            arraySelector: users
            allowJsonView: true
            reviewDefaultView: table
            labels:
              addRow: Add user
              searchPlaceholder: Search users
              rowCount: "{{ count }} users ({{ deleted }} removed)"
              deleteConfirm: Remove this user?
            columns:
              - key: id
                label: Id
                type: number
                editable: false
                defaultValue: 0
              - key: firstName
                label: First name
                type: string
                required: true
              - key: lastName
                label: Last name
                type: string
              - key: email
                label: Email
                type: string
                required: true
              - key: plan
                label: Plan
                type: select
                options:
                  - label: Free
                    value: free
                  - label: Team
                    value: team
                  - label: Enterprise
                    value: enterprise
              - key: orders
                label: Orders
                type: nested
                columns:
                  - key: orderId
                    label: Order Id
                    type: string
                  - key: item
                    label: Item
                    type: string
                    required: true
                  - key: quantity
                    label: Qty
                    type: number
                  - key: status
                    label: Status
                    type: select
                    options:
                      - label: Pending
                        value: pending
                      - label: Shipped
                        value: shipped
                      - label: Delivered
                        value: delivered
                      - label: Cancelled
                        value: cancelled
                  - key: shipments
                    label: Shipments
                    type: nested
                    columns:
                      - key: carrier
                        label: Carrier
                        type: string
                      - key: tracking
                        label: Tracking
                        type: string
                      - key: events
                        label: Events
                        type: nested
                        columns:
                          - key: status
                            label: Status
                            type: string
                          - key: note
                            label: Note
                            type: string
                          - key: meta
                            label: Meta
                            type: nested
                            columns:
                              - key: key
                                label: Key
                                type: string
                              - key: value
                                label: Value
                                type: string
                              - key: details
                                label: Details
                                type: nested
                                columns:
                                  - key: label
                                    label: Label
                                    type: string
                                  - key: info
                                    label: Info
                                    type: string
  steps:
    - id: log-summary
      name: Log user summary
      action: debug:log
      input:
        message: users=${{ parameters.users.length }} firstUser=${{ parameters.users[0].firstName }} firstOrderItem=${{ parameters.users[0].orders[0].item }}
    - id: log-table
      name: Log submitted table JSON
      action: debug:log
      input:
        message: ${{ parameters.users | dump(2) }}
```

</details>

### Example: Send the edited table to a pipeline

The following workflow loads five users from DummyJSON, lets developers edit and delete them, and sends the whole table to a Harness pipeline as one JSON string in a single run. It expects the `dummyjson` backend proxy endpoint from [Step 2](#step-2-load-rows-from-an-api), and the pipeline that follows it.

<details>

<summary>Example workflow.yaml</summary>

```yaml
apiVersion: harness.io/v1
kind: Workflow
name: Demo-Users-To-Pipeline
identifier: demo_users_to_pipeline
type: service
owner: team_idp
metadata:
  description: Sends the edited table to a Harness pipeline as one JSON string.
spec:
  parameters:
    - title: Pick users to send
      required:
        - token
        - users
      properties:
        token:
          title: Harness Token
          type: string
          ui:widget: password
          ui:field: HarnessAuthToken
        users:
          title: Users
          type: array
          items:
            type: object
            required:
              - firstName
            properties:
              id:
                type: number
                title: Id
              firstName:
                type: string
                title: First name
                minLength: 1
              lastName:
                type: string
                title: Last name
              email:
                type: string
                title: Email
          ui:field: CustomTableRenderer
          ui:options:
            path: proxy/dummyjson/users?limit=5
            arraySelector: users
            columns:
              - key: id
                label: Id
                type: number
                editable: false
                defaultValue: 0
              - key: firstName
                label: First name
                type: string
                required: true
              - key: lastName
                label: Last name
                type: string
              - key: email
                label: Email
                type: string
  steps:
    - id: trigger
      name: Send table to pipeline
      action: trigger:harness-custom-pipeline
      input:
        url: <PIPELINE_URL>
        inputset:
          users_json: ${{ parameters.users | dump }}
        apikey: ${{ parameters.token }}
  output:
    links:
      - title: Pipeline run
        url: ${{ steps.trigger.output.PipelineUrl }}
```

</details>

Replace `<PIPELINE_URL>` with the address of the pipeline in [Pipeline Studio](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/overview/pipeline-studio). The pipeline has one String variable, `users_json`, and one Shell Script step that prints what it receives. Replace `<PROJECT_ID>` with your project identifier.

<details>

<summary>Example pipeline YAML</summary>

```yaml
pipeline:
  name: users-table-receiver
  identifier: users_table_receiver
  projectIdentifier: <PROJECT_ID>
  orgIdentifier: default
  tags: {}
  stages:
    - stage:
        name: Receive table
        identifier: receive_table
        type: Custom
        spec:
          execution:
            steps:
              - step:
                  type: ShellScript
                  name: Print table JSON
                  identifier: print_table_json
                  spec:
                    shell: Bash
                    onDelegate: true
                    source:
                      type: Inline
                      spec:
                        script: |-
                          echo "Raw value received:"
                          cat <<'END_OF_JSON'
                          <+pipeline.variables.users_json>
                          END_OF_JSON
                    environmentVariables: []
                    outputVariables: []
                  timeout: 10m
  variables:
    - name: users_json
      type: String
      description: The table from the workflow, as one JSON string
      required: false
      value: <+input>
```

</details>

The **Print table JSON** step log displays the JSON list of users: deleted users are missing, and edited values appear as the developer saved them.

***

## Reference

### Configuration model

Three rules connect the JSON Schema half of a `CustomTableRenderer` property to its UI options:

1. **JSON Schema decides what is valid and what is submitted.** The table validates each row against `items` and submits an array of row objects.
2. **`columns` decides what the developer sees.** Each column `key` must match a property name under `items.properties`. The table displays only the columns you declare. A field without a column stays in the row, so it still reaches the submitted value. When you omit `columns`, the table infers the columns from the loaded rows.
3. **Child records repeat the same pattern one level down.** A property that is an array of objects in the schema becomes a child table when its column has `type: nested` and its own `columns` list.

The `title` of a schema property is the field name in the schema. The column header comes from the column `label`, and falls back to `key` when you omit `label`.

### Match schema types to column types

Use the following table to declare each field on both halves. The left column is what you write under `items.properties`, and the right column is what you write in the matching entry under `ui:options.columns`.

| Cell you want                      | JSON Schema property                                                              | Column entry                          |
| ---------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------- |
| Text                               | `type: string`                                                                    | `type: string` (default)              |
| Number                             | `type: number`                                                                    | `type: number`                        |
| Checkbox                           | `type: boolean`                                                                   | `type: boolean`                       |
| Dropdown                           | `type: string` with `enum`                                                        | `type: select` with `options`         |
| Date                               | `type: string` with `format: date`                                                | `type: date`                          |
| Date and time                      | `type: string` with `format: date-time`, or `type: number` for epoch milliseconds | `type: datetime`                      |
| JSON object                        | `type: object`                                                                    | `type: json`                          |
| List of plain values, such as tags | `type: array` with `items.type: string`                                           | `type: json`                          |
| Child table                        | `type: array` with `items.type: object` and `properties`                          | `type: nested` with its own `columns` |
| Required value                     | Key listed under `items.required`, plus `minLength: 1` for strings                | `required: true`                      |

### Nesting at a glance

A row can hold a child table, and each child row can hold its own child table. The [complete example](#complete-example) on this page uses the following structure: all four nested levels, plus a fifth level that opens as a JSON editor.

```
Users                 Top-level table
└── Orders            Nested level 1 (each user has orders)
    └── Shipments     Nested level 2 (each order has shipments)
        └── Events    Nested level 3 (each shipment has tracking events)
            └── Meta  Nested level 4 (each event has key-value pairs)
                └── Details  Level 5, beyond the limit: opens as a JSON editor
```

{% hint style="info" %}
Beyond the fourth nested level, the table renders child data in a JSON editor instead of another table.
{% endhint %}

### Column options

Each entry under `ui:options.columns` accepts the following fields.

| Field          | Required     | Description                                                                                 |
| -------------- | ------------ | ------------------------------------------------------------------------------------------- |
| `key`          | Yes          | Property name on the row object. Must match a property under `items.properties`.            |
| `label`        | No           | Column header. Falls back to `key`.                                                         |
| `type`         | No           | `string` (default), `number`, `boolean`, `select`, `json`, `date`, `datetime`, or `nested`. |
| `options`      | For `select` | Dropdown values as `label` and `value` pairs. The grid displays the stored `value`.         |
| `columns`      | For `nested` | Column list for the child table. Accepts the same fields as this table.                     |
| `required`     | No           | Marks the cell as required during inline editing.                                           |
| `editable`     | No           | When `false`, developers cannot edit the cell inline.                                       |
| `sortable`     | No           | When `false`, developers cannot sort the column. Nested columns are never sortable.         |
| `searchable`   | No           | When `false`, search ignores the column.                                                    |
| `hidden`       | No           | Hides the column from the grid and from search.                                             |
| `width`        | No           | Column width in pixels, for example `240`.                                                  |
| `placeholder`  | No           | Placeholder text in the cell editor.                                                        |
| `defaultValue` | No           | Value that a new row starts with.                                                           |

{% hint style="info" %}
**Legacy option:** `headers` still accepts simple columns as a comma-separated string, a list of keys, or a list of `key` and `label` objects. Use `columns` for new tables, as it supports typed editors, validation, and nested tables.
{% endhint %}

### Table behavior options

| Option                        | Default         | Description                                                                                           |
| ----------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- |
| `path`                        | Not set         | API path that loads the rows. With no `path`, the table starts empty and developers add rows by hand. |
| `arraySelector` or `selector` | Whole response  | Path to the value in the API response that becomes the table rows.                                    |
| `search`                      | `true`          | Displays the search box.                                                                              |
| `sortable`                    | `true`          | Enables sorting from the column headers.                                                              |
| `pagination`                  | `true`          | Displays pagination when the filtered table has rows.                                                 |
| `pageSize`                    | `20`            | Rows per page. Developers can also pick 5, 10, 20, 50, or 100.                                        |
| `allowAdd`                    | `true`          | Displays the add action in the toolbar, and the **+ Add** bar under nested tables.                    |
| `allowEdit`                   | `true`          | Displays the inline edit action.                                                                      |
| `allowDelete`                 | `true`          | Displays the delete action and the deleted count in the row count.                                    |
| `allowDuplicate`              | `true`          | Displays the duplicate action on rows at every table level.                                           |
| `allowUndo`                   | `true`          | Displays undo for deleted rows and the bulk undo actions.                                             |
| `statusFilter`                | `true`          | Displays the all, new, deleted, and errors filter.                                                    |
| `refetch`                     | `true`          | Displays **Refetch data**. The confirmation warns that the reload overwrites local changes.           |
| `selectable`                  | `true`          | Displays the row checkboxes and enables bulk delete and bulk undo.                                    |
| `readOnly`                    | `false`         | Makes the table view-only and hides the actions column, the status filter, and the selection.         |
| `showRowCount`                | `true`          | Displays the row count in the toolbar.                                                                |
| `allowJsonView`               | `true`          | Displays the **Table** and **JSON** toggle on the review step.                                        |
| `reviewDefaultView`           | `table`         | The view that the review toggle opens on, `table` or `json`. Ignored when `allowJsonView` is `false`. |
| `labels`                      | Not set         | Text overrides. Go to [Labels](#labels).                                                              |
| `title` and `description`     | From the schema | Override the label and help text that the field takes from the schema.                                |

### Request options

| Option            | Default | Description                                                                                                                                                                                                                          |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `useDirectApi`    | `false` | When `true`, the field sends the request same-origin with cookies, without the backend proxy. The API must accept cookie authentication from IDP.                                                                                    |
| `params`          | Not set | Query parameters added to the request.                                                                                                                                                                                               |
| `request.method`  | `GET`   | `GET`, `POST`, `PUT`, or `PATCH`.                                                                                                                                                                                                    |
| `request.headers` | Not set | Extra request headers.                                                                                                                                                                                                               |
| `request.body`    | Not set | JSON body for `POST`, `PUT`, and `PATCH`.                                                                                                                                                                                            |
| `appendUser`      | Not set | Copies the named fields of the signed-in user onto the request.                                                                                                                                                                      |
| `setContextData`  | Not set | Writes values from the current table data into [form context](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflows-tutorials/dynamic-picker.md#understand-form-context) for later fields. |

The following table reads a text field on the same step to decide how many users to load:

```yaml
userLimit:
  title: How many users to load
  type: string
  default: "10"
users:
  title: Users
  type: array
  # ...
  ui:field: CustomTableRenderer
  ui:options:
    path: proxy/dummyjson/users?limit={{ parameters.userLimit }}
    arraySelector: users
```

* `path`, `params`, `request.headers`, and `request.body` accept Nunjucks templates. Use `{{ parameters.<propertyId> }}` or `{{ formContext.<key> }}` to read other fields on the step. The table waits to fetch until every referenced field has a value. After the first load, changing a referenced field does not reload the table: the developer clicks **Refetch data** to load rows for the new value. To avoid a load with a half-typed value, put the referenced field on an earlier form page.
* `appendUser.location` is `headers` by default, and accepts `headers`, `query`, `body`, or a list of those. The field skips empty user fields. The `body` location applies only to `POST`, `PUT`, and `PATCH`. When `appendUser` is set, the table also waits for the signed-in user to load. Go to [Pass user information to dynamic pickers](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflows-tutorials/dynamic-picker.md#pass-user-information-to-dynamic-pickers) for the available user fields.
* `setContextData` runs after each fetch and after each edit. A plain string is a path into the current table value, such as `0.owner` for the owner of the first row. A string that contains `{{ }}` is a Nunjucks template, in which `value` and `response` are the current table value, and `parameters` and `formContext` are the step values.

### Supported response shapes

The value that `arraySelector` points to can take any of the following shapes. The field submits its value in the same shape. Declare the table property as `type: array` for a list of rows. With `type: object`, the field wraps a list as `{ "items": [ ... ] }`.

| Response value                       | Table rows                                                    | Submitted value                                |
| ------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------- |
| Array of objects                     | One row per object                                            | The same array                                 |
| Array of plain values                | One row per value, in a `value` column                        | The same array                                 |
| Object whose values are objects      | One row per entry, with a `key` column plus the object fields | The object, rebuilt from the `key` of each row |
| Object whose values are plain values | Rows of `key` and `value`                                     | The object, rebuilt from those pairs           |

### Labels

Set these keys under `ui:options.labels`.

| Key                                                           | Default text                                                                      |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `addRow`                                                      | Add table row (the top-level add button)                                          |
| `duplicateRow`                                                | Duplicate                                                                         |
| `deleteRow`                                                   | Delete (also the title and the confirm button of the delete confirmation)         |
| `deleteConfirm`                                               | Delete this table row?                                                            |
| `deleteSelected`                                              | Delete selected table rows                                                        |
| `deleteSelectedConfirm`                                       | Delete the `{{ count }}` selected table rows?                                     |
| `undoDelete`                                                  | Undo delete                                                                       |
| `undoDeletedRows` and `undoAddedRows`                         | Undo deleted rows, and Undo added rows                                            |
| `actions`                                                     | Actions                                                                           |
| `refetchRows`                                                 | Refetch data (also the title and the confirm button of the refetch confirmation)  |
| `refetchConfirm`                                              | Fetch the latest table data from the API? Your local changes will be overwritten. |
| `searchPlaceholder`                                           | Search table rows                                                                 |
| `emptyTable`                                                  | No table rows yet. Click Add button to add a row.                                 |
| `filterAll`, `filterNew`, `filterRemoved`, and `filterErrors` | Text of the status filter options                                                 |
| `selectAll` and `selectRow`                                   | Accessible labels of the selection checkboxes                                     |
| `rowCount`                                                    | `{{ count }}` table rows                                                          |
| `expandRow` and `collapseRow`                                 | Accessible labels of the expand and collapse chevron                              |

***

## Frequently asked questions

<details>

<summary>The field displays "CustomTableRenderer configuration error". What is wrong?</summary>

The `ui:options` block is not valid. Check that every column has a `key`, that each `type` is one of the supported column types, that every `select` column has `options`, that every `nested` column has `columns`, and that the indentation places `ui:field` and `ui:options` at the same level as `type` and `items`.

</details>

<details>

<summary>The field displays "Unable to load table data from the API". How do I fix it?</summary>

The request through the backend proxy did not succeed. Confirm that `path` is in the format `proxy/<endpoint-name>/<api-path>`, that the endpoint name matches the one declared under Configure → Plugins → Configure Backend Proxies, and that any secret referenced in the proxy headers exists.

</details>

<details>

<summary>Why is the table empty even though the API returns data?</summary>

Check `arraySelector` first. It has to point to the value that holds the rows. If the response body is itself the array, remove `arraySelector`. If the rows are nested, set it to the key that holds them, such as `users`.

</details>

<details>

<summary>Why are rows from my API highlighted in red?</summary>

The rows do not match the JSON Schema of the property. A common cause is an API that returns `null` for an empty field while the schema declares `type: string`. Declare the property as `type: [string, "null"]` to accept `null`. Use the Errors filter to list every row that fails.

</details>

<details>

<summary>Why does a field from the API not appear as a column?</summary>

The table displays only the columns declared under `columns`. Add a column whose `key` matches the field, and add the matching property under `items.properties`. A column with `hidden: true` also stays out of the grid and out of search. A field without a column still reaches the submitted value, as the row keeps it.

</details>

<details>

<summary>Does Custom Table Renderer replace JSON Schema?</summary>

No. JSON Schema still defines the submitted structure. The table uses it to mark invalid rows, to validate inline saves, and to validate the JSON editor beyond the fourth nested level. Custom Table Renderer adds the editing experience on top of that structure.

</details>

<details>

<summary>Does the submitted value include deleted rows or table markers?</summary>

No. The field submits standard JSON in the shape of the declared schema. The table leaves out deleted rows at every nesting level and removes its added and deleted markers before later workflow steps run. Fields that the API returned stay in each row, even when no column displays them.

</details>

<details>

<summary>What happens to local edits when a developer clicks Refetch data?</summary>

After the developer confirms, the table reloads the rows from the API, and that response replaces the local adds, edits, and deletes. Set `refetch: false` when a reload would discard edits that developers are expected to keep.

</details>

<details>

<summary>Can developers duplicate rows inside a nested table?</summary>

Yes. The duplicate action is available in nested tables as well as on top-level rows. Duplicating a row also copies its nested rows.

</details>

<details>

<summary>How deep can the nesting go?</summary>

Child tables go up to four nested levels. Beyond that, expanding a row opens a JSON editor that validates the content against the schema. Two or three levels are the easiest to scan.

</details>

<details>

<summary>Why does every row I add turn red, with an error such as "'Users 0 Id' must be number"?</summary>

A column with `editable: false` stays empty on rows that developers add, and the empty value fails the schema rule for that field, here `type: number`. Add a `defaultValue` that passes the rule, such as `defaultValue: 0`, to that column, or set `allowAdd: false` if developers should not add rows. Go to [Step 3](#step-3-add-cell-editors-and-validation) for an example.

</details>

<details>

<summary>Why does the pipeline step fail with "Token is not valid"?</summary>

Check the spelling of the `apikey` input on the `trigger:harness-custom-pipeline` step. It must be all lowercase. If the case differes (e.g., `apiKey`), the step does not receive the token, and the pipeline run fails with `Pipeline Execution failed: Token is not valid`. Also confirm that the form has a `token` property with `ui:field: HarnessAuthToken`.

</details>

<details>

<summary>Can I preview Custom Table Renderer in the Workflow Playground?</summary>

Only partially. The playground does not render advanced inputs or live API responses accurately. Test the table in an actual workflow execution.

</details>

{% @harness-feedback/feedback %}
