DataTable

Opinionated data grid with sort, selection, filters, and pagination.

Introduction

DataTable is an opinionated grid for columns and rows: sorting, selection, filters, search, empty and loading states, and pagination wiring. It composes Table for layout, sticky header, and column alignment. size, variant, full, striped, hoverable, and rounded are forwarded to Table.

When to use: Interactive datasets where the app owns fetch and DataTable owns chrome. Use Table for static markup you compose yourself.

Compared to similar components:

• Table — Presentational primitives (table / thead / tbody). No sort, selection, or pager.
• Pagination — Page controls. DataTable renders Pagination when page is set with a total, or when client paging slices rows.
• List — A vertical index of items. Use List for navigation rows; use DataTable when values line up across columns and need grid chrome.

Use the framework selector in the site header to switch between React and Vue.

Import

import { DataTable } from "@bridge-ui/vue/Components/DataTable";

import { DataTable } from "@bridge-ui/react/Components/DataTable";

Basic usage

Pass columns and rows. Set sortable on a column and bind sorting so header clicks cycle unsorted → ascending → descending. Cell text defaults to row[id] (or accessor) when no renderer is set.

Variants

Chrome matches Table: plain (default), ghost, or bordered. Built-in Pagination follows the pairing unless slots.pagination overrides it.

striped and hoverable are independent of variant. full={false} sizes columns to content; the bordered wrapper, per-page Select, and pagination follow that width. stickyHeader pins header cells to the page; "boxed" pins them inside the wrapper — set a max height on classes.wrapper.

Pagination

Built-in Pagination when page is set with pageCount or totalCount (server fetch stays in the app). page + perPage without those totals slices rows locally. perPage also renders a Select (perPageOptions, default 10 / 25 / 50 / 100).

When page and a total are set, DataTable does not sort or filter rows locally — bind sorting / filters / page and fetch the current page in the app. With perPage, the per-page Select and pager sit on opposite ends when they fit on one row of the bar; they stack and center when they overflow. Without perPage, the pager aligns to the end. Replace the controls with slots.pagination and slots.perPage.

Selection

Pass selection (always string[]) and getRowId. selectionMode="multiple" (default) uses checkboxes and select-all. selectionMode="single" uses radios and keeps at most one id.

Filters

Set filters on a column to show a funnel in that header. The panel uses checkboxes (filterMultiple, default) or radios (filterMultiple={false}), and Select all items for multiple filters. Nested children render as a group. OK commits; Reset clears the draft (commit on OK); closing without OK discards it.

Set searchable on a column to add a text field in that same overlay. Queries live in columnSearch (column id → string) and filter rows — they do not filter the option list. Hidden columns skip their column-search queries.

Column filters open in a FieldOverlay. Default filterOverlay is auto (menu on desktop, drawer on mobile). Pass menu, modal, or drawer to pin a shell.

Search and toolbar

Pass search and/or onSearchChange to show a search field in the toolbar. Client-side tables filter visible columns; server-paged tables emit the query only.

slots.toolbar is the leading region. slots.toolbarActions sits in the end cluster beside Columns and Search. The toolbar shows when either slot is set, or when Columns / Search are enabled.

Sticky columns

sticky="start" or sticky="end" pins a column while the table scrolls horizontally. Selection and expand chrome pin to start when any data column uses sticky="start". Set width on pinned columns so offsets stay stable; pinned columns without a parseable width fall back to 120px. Keep those widths modest so other columns stay visible on small screens. Columns need enough width (or a constrained wrapper) so the table overflows and a horizontal scrollport appears.

Column classes

classes.header and classes.cell merge onto that column’s th / td (body and footer). Use width utilities for breakpoint-based sizing. Do not set width on the same column when the class should control width — inline width wins.

Column visibility

Pass hiddenColumns and/or onHiddenColumnsChange to show a Columns icon in the toolbar. hideable={false} keeps a column out of the toggle (or disabled). At least one column stays visible.

The panel opens in a FieldOverlay. Default columnsOverlay is auto (menu on desktop, drawer on mobile). Pass menu, modal, or drawer to pin a shell.

When unset, columnsShowFooter is true for modal / drawer (false for menu). Reset restores hideable columns; OK commits and closes. Closing without OK discards the draft.

Expand

Controlled expanded row ids. slots.expanded renders in a spanning row under the data row.

Empty, loading, and footer

Empty rows show a default empty state; slots.empty replaces it. loading keeps the table visible. loadingVariant="overlay" (default) dims the table with a spin; loadingVariant="bar" dims the table and draws a progress line under the header. slots.loading replaces the indicator. slots.footer renders below the table, above pagination.

Item slots

cell on a column is for portable renderers. An item slot wins: React slots.item.{id}, Vue #item.{id}.

Summary

Set summary on a column to render a footer row over the current (filtered) rows. Chrome cells stay empty. Set ellipsis on a column to truncate overflowing cell text; the tooltip uses the column accessor.

Related components

Table, Pagination, List, Select, Menu

Accessibility

• DataTable keeps a real table with thead / tbody / optional tfoot.
• Sortable headers set aria-sort (none / ascending / descending).
• Selection checkboxes and radios are named Select row and Select all rows.
• Filter, Columns, and Search controls are named buttons/fields. Expand uses Expand row.
• loading sets aria-busy on the table.

Anatomy

<div> <!-- DataTable root -->
  <div> <!-- toolbar: slots.toolbar, Columns, slots.toolbarActions, Search -->
  <div> <!-- frame: hugs table when full is false -->
    <div> <!-- table + loading overlay -->
      <table> <!-- Table -->
        <thead> <!-- header row, optional bar loading -->
        <tbody> <!-- data rows, expand rows, empty state -->
        <tfoot> <!-- summary -->
    <div> <!-- slots.footer -->
    <div> <!-- per-page Select + Pagination -->
</div>

Use classes for root, toolbar, wrapper, table, header, body, row, head, cell, empty, loading, footer, search, pagination, and perPage. Each column also accepts classes.header and classes.cell.

API

DataTable

Column