Table

Usage#

import { Table, useTable, CellText, type ColumnConfig } from '@backstage/ui';

const columns: ColumnConfig<DataType>[] = [
  { id: 'name', label: 'Name', isRowHeader: true, cell: item => <CellText title={item.name} /> },
  { id: 'owner', label: 'Owner', cell: item => <CellText title={item.owner} /> },
];

function MyTable() {
  const { tableProps } = useTable({
    mode: 'complete',
    data,
  });

  return <Table columnConfig={columns} {...tableProps} />;
}

Core Concepts#

The Table component is designed around a hook + component pattern:

• useTable manages data fetching, pagination state, sorting, and filtering. It returns tableProps that you spread onto the Table component.
• Table handles rendering - columns, rows, cells, and interactions.

The hook supports three modes for different data scenarios:

• complete - You have all data available upfront (client-side)
• offset - Your API uses offset/limit pagination
• cursor - Your API uses cursor-based pagination

// What useTable returns
const {
  tableProps,  // Spread onto <Table />
  reload,      // Trigger data refetch
  search,      // { value, onChange } for search input
  filter,      // { value, onChange } for filters
} = useTable({ ... });

Controlled vs uncontrolled state

By default, useTable manages sort, search, and filter state internally. Pass initialSort, initialSearch, or initialFilter to set starting values.

For full control over state, use the controlled props instead:

• sort / onSortChange
• search / onSearchChange
• filter / onFilterChange

Common Patterns#

Sorting#

Columns can be made sortable by adding isSortable: true to the column configuration. When sortable, clicking a column header cycles through ascending, descending, and unsorted states. A visual indicator shows the current sort direction.

With mode: 'complete', sorting happens client-side. Provide a sortFn that receives the full dataset and the current sort descriptor, and returns the sorted array. You can also set an initialSort to define the default sort when the table first renders. For server-side sorting with offset or cursor modes, see Server-Side Data.

Pagination#

Configure page size and available options through paginationOptions. The table displays navigation controls automatically.

const { tableProps } = useTable({
  mode: 'complete',
  data,
  paginationOptions: {
    pageSize: 10,
    pageSizeOptions: [10, 25, 50],
  },
});

Search#

The useTable hook returns a search object with value and onChange properties, ready to connect to a search input. With mode: 'complete', provide a searchFn that filters the dataset based on the search query.

The search state is debounced internally, so rapid typing doesn't trigger excessive re-filtering. When the search query changes, pagination resets to the first page automatically.

For server-side search with offset or cursor modes, the search query is passed to your getData function. See Server-Side Data.

Row Selection#

Tables support row selection with two configuration options: mode and behavior.

Selection mode controls how many rows can be selected:

• single - Only one row can be selected at a time
• multiple - Any number of rows can be selected, with a header checkbox for select-all

Selection behavior controls the interaction style:

• toggle - Checkboxes appear for selection. Click a checkbox to select/deselect.
• replace - No checkboxes. Click a row to select it (replacing previous selection). Use Cmd/Ctrl+click to select multiple rows.

Selection state can be managed in two ways:

• Controlled - Pass both selected and onSelectionChange to fully manage state externally
• Uncontrolled - Pass only onSelectionChange to let the Table manage state while receiving change notifications

Row Actions#

Rows can respond to user interaction in two ways: navigating to a URL or triggering a callback.

Use getHref when rows should link to detail pages. The entire row becomes clickable and navigates on click. Links within cells remain independently clickable.

<Table
  columnConfig={columns}
  rowConfig={{
    getHref: item => `/catalog/${item.namespace}/${item.name}`
  }}
  {...tableProps}
/>

Use onClick for custom actions like opening a panel or triggering a dialog.

<Table
  columnConfig={columns}
  rowConfig={{
    onClick: item => openDetailPanel(item)
  }}
  {...tableProps}
/>

When combining row actions with selection, the interaction depends on selection behavior:

• toggle: Clicking a row triggers its action when nothing is selected. Once any row is selected, clicking anywhere on the row toggles selection instead.
• replace: Single click selects the row. Double-click triggers the row action.

You can also disable specific rows from being clicked using getIsDisabled:

<Table
  columnConfig={columns}
  rowConfig={{
    onClick: item => openDetailPanel(item),
    getIsDisabled: item => item.status === 'archived',
  }}
  {...tableProps}
/>

Empty State#

When the table has no data to display, provide an emptyState to show a helpful message instead of an empty table body. Consider providing different messages depending on context - an empty search result is different from a table with no data at all.

Server-Side Data#

When your data comes from an API with server-side pagination, use offset or cursor mode instead of complete. The key difference: instead of providing all data upfront, you provide a getData function that fetches data for the current page.

Offset Pagination#

Use mode: 'offset' when your API accepts offset and limit (or skip and take) parameters.

const { tableProps } = useTable({
  mode: 'offset',
  getData: async ({ offset, pageSize, sort, search, filter, signal }) => {
    const response = await fetch(
      `/api/items?offset=${offset}&limit=${pageSize}&q=${search}`,
      { signal }
    );
    const { items, totalCount } = await response.json();

    return {
      data: items,
      totalCount,
    };
  },
  paginationOptions: {
    pageSize: 20,
    pageSizeOptions: [20, 50, 100],
  },
});

The signal parameter is an AbortSignal - pass it to fetch so in-flight requests are cancelled when the user navigates away or triggers a new query.

Cursor Pagination#

Use mode: 'cursor' when your API uses cursor-based pagination (common with GraphQL or APIs that return nextCursor/prevCursor tokens).

const { tableProps } = useTable({
  mode: 'cursor',
  getData: async ({ cursor, pageSize, sort, search, signal }) => {
    const response = await fetch(
      `/api/items?cursor=${cursor ?? ''}&limit=${pageSize}&q=${search}`,
      { signal }
    );
    const { items, nextCursor, prevCursor, totalCount } = await response.json();

    return {
      data: items,
      nextCursor,
      prevCursor,
      totalCount, // optional - enables "X of Y" display
    };
  },
  paginationOptions: {
    pageSize: 20,
    pageSizeOptions: [20, 50, 100],
  },
});

Loading States#

When fetching data, the table shows a loading state. If the user triggers a new query (by paginating, sorting, or searching) while previous data is displayed, the table enters a "stale" state where it continues showing the previous data until new data arrives. This prevents jarring layout shifts.

You can access these states via tableProps.loading and tableProps.isStale if you need to render additional loading indicators.

Combining Features#

Real-world tables often combine multiple features. Here's an example with search, sorting, pagination, and row selection working together.

Custom Tables#

For most use cases, useTable + Table provides everything you need. When you need more control, there are several ways you can customize your table.

Custom Row and Header Rendering#

Use a render function for rowConfig when you need to customize individual rows based on their data - for example, highlighting rows that require attention. Use header in column config to customize header cell content.

Using Primitives Directly#

When the Table component doesn't support your use case, you can compose with the lower-level primitives: TableRoot, TableHeader, TableBody, Column, and Row.

API Reference#

useTable#

The useTable hook manages data fetching, pagination, sorting, and filtering.

Options

Return Value

Table#

The main table component.

ColumnConfig#

CellText#

Inherits all React Aria Cell props.

CellProfile#

Inherits all React Aria Cell props.

TablePagination#

Primitives#

Low-level components for building custom table layouts.

TableRoot

Inherits all React Aria Table props.

TableHeader

Inherits all React Aria TableHeader props.

TableBody

Inherits all React Aria TableBody props.

Column

Inherits all React Aria Column props.

Row

Inherits all React Aria Row props.

Cell

Inherits all React Aria Cell props.

Changelog#

Version 0.11.0#

Breaking Changes

• Breaking Redesigned Table component with new useTable hook API.

  • The Table component (React Aria wrapper) is renamed to TableRoot
  • New high-level Table component that handles data display, pagination, sorting, and selection
  • The useTable hook is completely redesigned with a new API supporting three pagination modes (complete, offset, cursor)
  • New types: ColumnConfig, TableProps, TableItem, UseTableOptions, UseTableResult

  New features include unified pagination modes, debounced query changes, stale data preservation during reloads, and row selection with toggle/replace behaviors. #32050

  Migration Guide:

  1. Update imports and use the new useTable hook:

  -import { Table, useTable } from '@backstage/ui';
  -const { data, paginationProps } = useTable({ data: items, pagination: {...} });
  +import { Table, useTable, type ColumnConfig } from '@backstage/ui';
  +const { tableProps } = useTable({
  +  mode: 'complete',
  +  getData: () => items,
  +});
  

  2. Define columns and render with the new Table API:

  -<Table aria-label="My table">
  -  <TableHeader>...</TableHeader>
  -  <TableBody items={data}>...</TableBody>
  -</Table>
  -<TablePagination {...paginationProps} />
  +const columns: ColumnConfig<Item>[] = [
  +  { id: 'name', label: 'Name', isRowHeader: true, cell: item => <CellText title={item.name} /> },
  +  { id: 'type', label: 'Type', cell: item => <CellText title={item.type} /> },
  +];
  +
  +<Table columnConfig={columns} {...tableProps} />
  

Changes

• Fixed Table sorting indicator not being visible when a column is actively sorted. #32350

• Added support for column width configuration in Table component. Columns now accept width, defaultWidth, minWidth, and maxWidth props for responsive layout control. #32336

• Added support for custom pagination options in useTable hook and Table component. You can now configure pageSizeOptions to customize the page size dropdown, and hook into pagination events via onPageSizeChange, onNextPage, and onPreviousPage callbacks. When pageSize doesn't match any option, the first option is used and a warning is logged. #32321

• Fixed missing border styles on table selection cells in multi-select mode. #32369

• Added className and style props to the Table component. #32342

Version 0.10.0#

Changes

• Added row selection support with visual state styling for hover, selected, and pressed states. Fixed checkbox rendering to only show for multi-select toggle mode. #31907

Version 0.9.0#

Changes

• Fixed Table Row component to properly support opening links in new tabs via right-click or Cmd+Click when using the href prop. #31680