Table

Usage

forge-table renders rows and columns from two JS properties — data (an array of row objects) and columnConfigurations (column definitions) — rather than static HTML attributes, plus select/multiselect, filter, dense/roomy, resizable, and fixedHeaders. It’s a basic data table, not a fully-featured grid — use it when content has three or more well-defined, sortable dimensions and users need to compare across rows. For content that’s primarily scanned rather than compared, or that’s mostly viewed on mobile, use a list instead. And if you need virtual or infinite scrolling, or more advanced filtering than a single input per column, reach for a dedicated grid library like AG Grid instead — forge-table intentionally stays basic.

Rules

Basic usage

Set data and columnConfigurations as JS properties to populate the table — they can’t be expressed as static HTML attributes, so explore the live behavior in the Storybook playground above. The markup below shows the table’s underlying structure using the plain, CSS-only escape hatch instead of the full component.

<table class="forge-data-table">
  <thead>
    <tr>
      <th>
        Column 1
      </th>
      <th>
        Column 2
      </th>
      <th>
        Column 3
      </th>
      <th>
        Column 4
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        Row 1, Col 1
      </td>
      <td>
        Row 1, Col 2
      </td>
      <td>
        Row 1, Col 3
      </td>
      <td>
        Row 1, Col 4
      </td>
    </tr>
    <tr>
      <td>
        Row 2, Col 1
      </td>
      <td>
        Row 2, Col 2
      </td>
      <td>
        Row 2, Col 3
      </td>
      <td>
        Row 2, Col 4
      </td>
    </tr>
    <tr>
      <td>
        Row 3, Col 1
      </td>
      <td>
        Row 3, Col 2
      </td>
      <td>
        Row 3, Col 3
      </td>
      <td>
        Row 3, Col 4
      </td>
    </tr>
  </tbody>
</table>

Inside a card

Place a table in a forge-card no-padding with a forge-scaffold, so it runs edge to edge. Put the table title and icon actions (filter, export, more) in the header toolbar, and a forge-paginator in an inverted footer toolbar. The primary page action, like “New order”, goes in the page’s body header, not the card.

<forge-card no-padding>
  <forge-scaffold>
    <forge-toolbar slot="header">
      <h3 slot="start" class="forge-typography--heading3">Orders</h3>
      <forge-icon-button slot="end" density="medium" aria-label="Filter orders">
        <forge-icon name="filter_list"></forge-icon>
      </forge-icon-button>
    </forge-toolbar>
    <forge-table slot="body"></forge-table>
    <forge-toolbar slot="footer" inverted>
      <forge-paginator slot="end"></forge-paginator>
    </forge-toolbar>
  </forge-scaffold>
</forge-card>

Configuring columns

Each entry in columnConfigurations describes one column: header (and optional footer) text, the property to read from each row in data, and whether it’s sortable (with initialSort marking the column sorted by default) or filter-able.

import type { IColumnConfiguration } from "@tylertech/forge";

const columnConfigurations: IColumnConfiguration[] = [
  { header: "First name", property: "firstName", sortable: true, initialSort: true },
  { header: "Last name", property: "lastName", sortable: true },
  { header: "Age", property: "age", sortable: true },
];

tableEl.columnConfigurations = columnConfigurations;
tableEl.data = data;

Column filters

Set filter: true on a column and give it a filterDelegate to render a filter input in the header. Use the built-in TextFieldComponentDelegate or SelectComponentDelegate for common input types, or build a custom delegate by extending BaseComponentDelegate or FormFieldComponentDelegate — either way, the delegate is a consistent interface for getting/setting a value and toggling invalid/disabled/required on whatever component it wraps.

import { TextFieldComponentDelegate, SelectComponentDelegate } from "@tylertech/forge";

table.columnConfigurations = [
  {
    property: "name",
    header: "Name",
    filter: true,
    filterDelegate: () => new TextFieldComponentDelegate({ options: { placeholder: "Filter name..." } }),
  },
  {
    property: "color",
    header: "Favorite color",
    filter: true,
    filterDelegate: () => new SelectComponentDelegate({ props: { placeholder: "Filter color..." } }),
  },
];

Footer row

Set includeFooter to add a footer row, then give each column either a static footer string or a footerTemplate callback for custom content, like a computed average. Style footer cells individually via footerCellStyle.

tableEl.includeFooter = true;
tableEl.columnConfigurations = [
  { header: "First name", property: "firstName", footer: "Total" },
  {
    header: "Age",
    property: "age",
    footerTemplate: () => {
      const span = document.createElement("span");
      span.textContent = `Avg: ${average}`;
      return span;
    },
  },
];

Transforming values

Use a column’s transform callback to map a raw value to display text — a boolean to “Enabled”/“Disabled”, for example — without changing the underlying data.

{
  property: "active",
  header: "Status",
  transform: (value) => (value ? "Enabled" : "Disabled"),
}