DataTable

DataTable shows rows and columns as a spreadsheet does and scrolls both ways over any number of either. Only the cells in view are made, so a table of a million rows and ten thousand columns scrolls as a small one does. Rows, columns or cells select, with the pointer and the keyboard; columns have fixed widths, resize with a drag of their edge, move with a drag of their title, stay at the left while the others scroll, and sort. Titles can sit under group labels, and a cell or a title can be drawn by the app.

import { mount, signal, Text, View } from "nsh";
import { DataTable, type DataTableColumn, type DataTableSelection, type DataTableSort } from "nsh/base";
import { Log, Segmented, Split, ui, wide } from "./palette";

const NAMES = ["Ada", "Alan", "Grace", "Linus", "Margaret", "Dennis", "Barbara", "Ken"];
const CITIES = ["Oslo", "Lima", "Kyoto", "Cairo", "Perth", "Quito", "Turin", "Hanoi"];

type Person = { id: number; name: string; city: string; score: number };

const people: Person[] = Array.from({ length: 2000 }, (_, i) => ({
  id: i + 1,
  name: `${NAMES[i % NAMES.length]} ${i + 1}`,
  city: CITIES[(i * 7) % CITIES.length],
  score: (i * 37) % 1000,
}));

const columns: DataTableColumn[] = [
  { key: "id", title: "ID", width: 70, align: "end", fixed: true, sortable: true },
  { key: "name", title: "Name", width: 150, sortable: true },
  { key: "city", title: "City", width: 120, sortable: true },
  { key: "score", title: "Score", width: 90, align: "end", sortable: true },
];

// Sorting is the app's: the table reports the next sort (`onSortChange`),
// the app orders its rows and sets `sort`.
function App() {
  const mode = signal<"row" | "cell">("row");
  const sort = signal<DataTableSort | undefined>(undefined);
  const rows = signal<Person[]>(people);
  const events = signal<string[]>([]);
  const log = (line: string) => events.set([line, ...events()].slice(0, 4));

  const sortBy = (next: DataTableSort | undefined) => {
    sort.set(next);
    if (!next) return rows.set(people);
    const key = next.key as keyof Person;
    const sign = next.direction === "descending" ? -1 : 1;
    rows.set([...people].sort((a, b) => (a[key] < b[key] ? -sign : a[key] > b[key] ? sign : 0)));
  };

  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
      <Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>data table</Text>
      <Text style={{ color: ui().muted }}>Press a title to sort, drag its edge to resize or the title to move it</Text>

      <Split
        grow
        width={680}
        inspector={
          <>
            <Segmented label="selection" options={["row", "cell"] as const} value={mode()} onChange={(v) => mode.set(v)} />
            <Log title="events" lines={events()} minHeight={96} />
          </>
        }
      >
        <View style={{ height: wide() ? 360 : 320, ...ui().card, borderRadius: 14, overflow: "hidden" }}>
          <DataTable
            columns={columns}
            data={rows()}
            rowHeader
            stripe
            cellSelectable={mode() === "cell"}
            sort={sort()}
            onSortChange={(next) => {
              sortBy(next ?? undefined);
              log(`onSortChange: ${next ? `${next.key} ${next.direction}` : "none"}`);
            }}
            onSelectionChange={(s: DataTableSelection | null) => log(`onSelectionChange: ${s ? JSON.stringify(s) : "none"}`)}
            onColumnResize={(key, width) => log(`onColumnResize: ${key} ${Math.round(width)}`)}
            style={{ flex: 1 }}
          />
        </View>
      </Split>
    </View>
  );
}

mount(App);

DataTable owns behavior and comes with a look of its own built from the theme’s tokens: titles on muted, a border line between rows, a hover tint and a selection tint on primary. Each part takes the app’s styles over these defaults (classes and styles). Rust makes one with nsh_base::data_table(), TSX with <DataTable> from nsh/base.

use nsh_base::{DataTableColumn, data_table};
use nsh_core::ui::prelude::*;

fn column(key: &str, title: &str) -> DataTableColumn {
    let mut column = DataTableColumn::default();
    column.key = key.into();
    column.title = Some(title.into());
    column
}

fn table() -> impl IntoElement {
    data_table()
        .columns(vec![column("name", "Name"), column("city", "City")])
        .flex_1()
}

import { mount } from "nsh";
import { DataTable, type DataTableColumn } from "nsh/base";

const columns: DataTableColumn[] = [
  { key: "name", title: "Name", width: 160, sortable: true },
  { key: "city", title: "City", width: 120 },
  { key: "score", title: "Score", width: 90, align: "end" },
];

const rows = [
  { name: "Ada", city: "Oslo", score: 91 },
  { name: "Grace", city: "Lima", score: 87 },
  { name: "Linus", city: "Kyoto", score: 78 },
];

function App() {
  return <DataTable columns={columns} data={rows} class="flex-1" />;
}

mount(App);

The table fills the box the app gives it (flex-1, a height) and scrolls inside: vertically through the rows and sideways through the columns, with scroll bars (scrollbar={false} hides them, bounces={false} stops the bounce at the ends where a platform has one).

#Rows and columns

data is the rows: objects whose fields the columns’ keys name, or arrays the columns index by position. Numbers, booleans and strings show as text. A column is a DataTableColumn:

rowHeight is the height of a body row (default 32) and headerHeight the height of a title row (default the row height). rowHeader adds a column of row numbers at the left, which selects rows. stripe gives the odd rows the rowOdd part.

#Group labels

groups puts labels above the columns, the lowest level first. Each level is a list of { label, span } whose spans add up to the number of columns, or of the level below.

<DataTable
  columns={columns}
  data={rows}
  groups={[
    [{ label: "Person", span: 2 }, { label: "Result", span: 1 }],
  ]}
  class="flex-1"
/>

#Any number of rows

The table asks for rows by position, and the app serves them. rowCount is the total number of rows, data the rows the app holds, and dataStart the position of the first of them. Rows outside data are empty until the app supplies them. onVisibleRowsChange reports the rows in view, { start, end }, at every scroll step, and is the place to fetch the page around them.

const ROWS = 1_000_000;
const page = signal({ start: 0, rows: load(0) });

<DataTable
  columns={columns}
  data={page().rows}
  dataStart={page().start}
  rowCount={ROWS}
  onVisibleRowsChange={({ start, end }) => {
    // Keep the rows in view inside the page held.
    const held = page();
    if (start < held.start || end > held.start + held.rows.length) {
      const first = Math.max(0, start - 200);
      page.set({ start: first, rows: load(first) });
    }
  }}
  class="flex-1"
/>

For a list that grows at its end, set hasMore: onLoadMore fires once for each number of rows when the rows in view come within loadMoreThreshold (default 20) of the last. While loading is true it waits, and the loadingView slot shows over the rows. The empty slot shows when there are no rows.

Past a few million points of content the scroll bars span a scaled range, so a million rows still scroll to every row.

#Selection

Three switches decide what a press selects, as in gpui-component:

With cellSelectable and the row header hidden (rowHeader={false}), pressing the selected cell again selects its row. A press with Shift or the platform’s command key held selects a row only while selectOnModifierPress (default true), so an app that keeps its own multi-row selection handles those presses itself: onRowPress reports every press of the body with its row, the column under the pointer, the clicks in a row and the modifier keys held. A column whose selectable is false selects neither itself nor its cells.

Rows count from 0 in the data, and a column is its index among columns, whatever order the user moved them to. onSelectionChange reports what the user selected (null for nothing). The selection prop sets the selection from the app; leave it unset and the table keeps it. onDoublePress reports a row, a cell or a title pressed twice, and onContextMenu a secondary or long press with the point to open the app’s Menu at. Both name the cell under the pointer (its row and column), a row’s number (row only) or a title (column only). Until the next press, the cell a menu was asked for has the cellActive part, or its row the rowActive part where cells do not select.

Screen readers get a grid (named by accessibilityLabel) of column headers and cells, the selected ones said to be selected.

#Keyboard

Pressing the table, or reaching it with Tab (macOS, the web), gives it the keyboard until another press, the focus moving elsewhere or blur(); focus() gives it from the app. The table is one stop of Tab: inside it Tab moves the selection, and Escape gives the keyboard back.

loopSelection (default true) makes the arrow keys go around the ends.

#Sorting

A sortable column has a sort button at the end of its title, a small ghost button dimmed while the column is unsorted. Pressing it reports the next sort in the cycle of unsorted, ascending, descending and unsorted again, with onSortChange({ key, direction }) (null to clear). The table does not reorder the rows: the app sorts its data, or asks its server for rows in the new order, and sets sort so the title shows it. Because the app owns the order, sorting works the same over a million rows the app never holds.

<DataTable
  columns={columns}
  data={rows()}
  sort={sort()}
  onSortChange={(next) => {
    sort.set(next ?? undefined);
    rows.set(sorted(people, next));
  }}
  class="flex-1"
/>

#Resizing and moving columns

A drag of a column’s trailing edge resizes it within its minWidth and maxWidth, and onColumnResize(key, width) reports every step. Pressing the edge twice in a row fits the column to its widest text and title. A drag of a title moves the column, and a line shows where it will drop; onColumnMove reports { key, from, to, order }, order being the keys of all the columns in the order shown. Fixed columns stay among the fixed ones. resizableColumns and movableColumns turn both off for the table, and a column’s resizable and movable win over them.

#Live data

A quote table changes many times a second. The app formats the rows in view and a reach around them (it knows them from onVisibleRowsChange) and hands those over as data from dataStart, so an update costs what is on screen, whatever the number of rows. Rises and falls take their colors from the column’s positiveClass and negativeClass, applied natively to the cells whose value is above or below zero (or whose text starts with + or -).

const tone = { positiveClass: "text-green-600", negativeClass: "text-red-600" };
const columns: DataTableColumn[] = [
  { key: "symbol", title: "Symbol", fixed: true },
  { key: "price", title: "Price", align: "end", sortable: true },
  { key: "change", title: "Chg%", align: "end", ...tone },
];

Rows and columns are slots the table makes once and keeps: scrolling gives them other rows and columns to show, so a scroll, however long, changes texts and places only.

#Drawing cells and titles

renderCell draws the cells of the app’s own where a column is not just text (a badge, a button). It is called for the cells in view only, with a DataTableCell: row, column, key, text (what the table would show) and selected. The app looks up its own data by row. renderHeaderCell draws a title across its cell, told a DataTableHeaderCell: column, key, title, sort (the direction, or none) and selected.

<DataTable
  columns={columns}
  data={rows()}
  renderCell={(cell) =>
    cell.key === "status" ? (
      <View class={cell.text === "open" ? "rounded bg-green-500/20 px-2" : "rounded bg-muted px-2"}>
        <Text class="text-xs">{cell.text}</Text>
      </View>
    ) : (
      <Text class="px-2 text-sm">{cell.text}</Text>
    )
  }
  class="flex-1"
/>

fontFamily and fontSize (default 14) set the font of the cells, which the table also measures texts in to fit columns.

#The ref

ref gives a DataTableRef:

#Styling the parts

class and style style the table’s box. classes takes Tailwind classes by part and styles inline styles by part; a part’s classes come after its own default styles, so they win, and its styles win over its classes.

<DataTable
  columns={columns}
  data={rows()}
  stripe
  class="flex-1 rounded-lg border border-border"
  classes={{
    headerCell: "bg-secondary",
    rowSelected: "bg-primary/10",
    rowHover: "bg-muted/50",
    fixedEdge: "bg-border",
  }}
/>

#Props

#Events

#Related

• Editor and DiffView: the other data-heavy base components.
• Menu: the menu to open from onContextMenu.
• nsh/base: the other base components.