What GuiExpert Table is

GuiExpert Table is a data grid for web applications that work with large tabular data sets: tens of thousands to millions of rows, dozens to hundreds of columns. It renders only the cells inside the visible area – vertically and horizontally – so the size of the DOM depends on the size of the viewport, not on the size of the data.

The core, @guiexpert/table, is written in plain TypeScript and has no runtime dependencies. Thin wrappers make it available in Angular, React, Vue, Svelte, Solid and Preact and as a Web Component. Models, options, renderers and the API are identical in all of them.

• Model-driven

  The table does not copy your data. While rendering it asks a model for each visible cell: value, row height, span, CSS classes, renderer.

• Virtual in both directions

  Only visible rows and columns exist in the DOM. Fixed columns, header and footer stay in place while the body scrolls.

• One core for every framework

  What you learn and build once – models, renderers, options – works unchanged in every supported framework.

• Open by design

  Cells are plain DOM elements and colours are CSS variables. You decide what a cell contains and how the table looks.

Packages and frameworks

Every project needs the core. For a framework, add its wrapper – a small component that creates the table, forwards its events in the style of the framework and hands you the TableApi.

The wrappers declare their framework as a peer dependency. For Angular, the major version of the package follows the Angular major version (@guiexpert/angular-table@22 for Angular 22). For prototypes, @guiexpert/demo-table-models provides ready-made models (large data set, heatmap, tree and more).

Installation

Install the core and, if you use a framework, its wrapper:

npm install @guiexpert/table @guiexpert/react-table
# angular-table · vue3-table · svelte-table · solid-table · preact-table · webcomponent-table

Stylesheet

The core ships one stylesheet, css/main.css. It contains the colours as CSS variables (light and dark), the classes of the rendered cells and a few helper classes.

• Bundler (Vite, webpack, esbuild): import "@guiexpert/table/css/main.css";
• Plain HTML page: load it from a CDN – https://cdn.jsdelivr.net/npm/@guiexpert/table/css/main.css
• Angular: nothing to do – the component contains the styles.

.table-div {
  height: 500px;   /* or: height: calc(100vh - 120px); or flex: 1 in a flex column */
}

More on bundlers, CDN use and typical mistakes: chapter 4 (Installation).

The four building blocks

Every table consists of the same four parts – in plain TypeScript and in every framework: a host element, a table model (what to show), table options (how it behaves and looks) and a TableScope, which renders the table and returns the TableApi.

Without a framework you connect the four parts yourself:

import {
  EventAdapter, SimpleDomService, TableFactory, TableOptions, TableScope
} from "@guiexpert/table";
import "@guiexpert/table/css/main.css";

interface Order { id: number; customer: string; city: string; total: number; }

const orders: Order[] = [
  { id: 1, customer: "Miller Ltd.", city: "Berlin", total: 1250 },
  { id: 2, customer: "Acme Corp.", city: "Hamburg", total: 980 }
];

const tableModel = TableFactory.createTableModel({          // 2 · what to show
  rows: orders,
  properties: ["id", "customer", "city", "total"]
});

const tableScope = new TableScope(
  document.querySelector<HTMLDivElement>("#orders")!,       // 1 · host element with a height
  tableModel,
  new SimpleDomService(),
  { ...new TableOptions() },                                // 3 · how it behaves and looks
  new EventAdapter()                                        //     events – override what you need
);
tableScope.firstInit();                                     // 4 · render
const tableApi = tableScope.getApi();                       // scroll, sort, filter, export …

A framework wrapper takes over step 4: you pass tableModel and tableOptions as inputs or props and receive the TableApi with the tableReady event (Angular 22+: <guiexpert-table-signal [(tableApi)]="api"> – the API as a signal). The guides for each framework are listed under Packages and frameworks.

The table model

A table model is not a data array. It is an object that answers the questions the table asks while it renders: how many rows and columns are there, what is the value of a cell, how high is a row, does a cell span several columns, which CSS classes does it get. Its interface is TableModelIf.

Header and footer need answers to most of these questions, too. That is why a table model consists of three area models (AreaModelIf) – one each for header, body and footer – plus the column definitions. Fixed columns split every area again into west, center and east:

What an area model answers

The table asks these questions only for cells that are visible. A model can therefore compute its values on demand – two million rows do not require two million objects in memory.

Ready-made area models

Three ways to create a model

Choose the approach that matches your data. All three end in the same TableModelIf, and they can be combined – for example a body from an object array with a footer model of your own.

1 · From your data with TableFactory

TableFactory.createTableModel() covers most cases. Pass an array of objects with the properties to show – or with full column definitions (Column definitions):

const tableModel = TableFactory.createTableModel({
  rows: orders,
  properties: ["id", "customer", "city", "total"]      // the columns, in this order
});

Data that already comes as rows of values – CSV, matrices, reports – goes in as an array of arrays:

const tableModel = TableFactory.createTableModel({
  headerData: [["Name", "City", "Age"]],                // one or more header rows
  bodyData: [
    ["Anna", "Berlin", 34],
    ["Ben", "Hamburg", 28]
  ],
  footerData: [["", "Average", "31"]],
  columnSizes: [200, 150, 80]
});

All parameters: CreateTableModelPara.

2 · Assemble your own area models

Implement an area model when the data is computed, very large or loaded on demand – and pass it to the factory as bodyAreaModel, headerAreaModel or footerAreaModel. The base class AreaModel provides sensible defaults, so only a few methods are needed:

import { AreaModel, ColumnDef, TableFactory, px120, px200 } from "@guiexpert/table";

class MillionRowsModel extends AreaModel {
  constructor(private readonly rowCount: number) { super(); }

  override getRowCount(): number { return this.rowCount; }
  override getRowHeight(_rowIndex: number): number { return 34; }
  override getConstantRowHeight(): number | undefined { return 34; }   // constant-time scrolling
  override getValueAt(rowIndex: number, columnIndex: number): string | number {
    return columnIndex === 0 ? "id" + rowIndex : rowIndex * 3;          // computed on demand
  }
}

const tableModel = TableFactory.createTableModel({
  bodyAreaModel: new MillionRowsModel(2_000_000),
  columnDefs: [new ColumnDef("id", "ID", px120), new ColumnDef("value", "Value", px200)]
});

The same pattern gives you a footer with totals of the filtered rows (chapter 16 (Footer totals)) or a model that loads pages from a server (chapter 17 (Own AreaModel)).

3 · Extend an existing model

To change a single aspect, derive from a ready-made model and override one method. Here negative balances get the error colour:

import { AreaModelArrayOfArrays, TableFactory } from "@guiexpert/table";

class BalanceModel extends AreaModelArrayOfArrays<string | number> {
  override getCustomClassesAt(rowIndex: number, columnIndex: number): string[] {
    const value = this.getValueAt(rowIndex, columnIndex);
    return typeof value === "number" && value < 0 ? ["ge-table-color-error"] : [];
  }
}

const tableModel = TableFactory.createTableModel({
  headerData: [["Account", "Balance"]],
  bodyAreaModel: new BalanceModel("body", [["Cash", 1200], ["Loan", -350]], 34),
  columnSizes: [200, 120]
});

Spans, tooltips, renderers and editability work the same way: override getRowspanAt(), getTooltipAt(), getCellRenderer() or isEditable().

Column definitions

A ColumnDef describes one column: which property it shows, its header label and width, alignment, renderers, sorting and editing. Use the constructor for the short form and ColumnDef.create() for named parameters:

import { ColumnDef, ColumnDefIf, TableFactory, TrueFn, px80, px120, px200 } from "@guiexpert/table";

const columnDefs: ColumnDefIf[] = [
  new ColumnDef("id", "ID", px80),                     // property, header label, width
  ColumnDef.create({                                   // named parameters
    property: "customer",
    headerLabel: "Customer",
    width: px200,
    sortable: TrueFn
  }),
  ColumnDef.create({
    property: "total",
    headerLabel: "Total",
    width: px120,
    headerClasses: ["ge-table-text-align-right"],
    bodyClasses: ["ge-table-text-align-right"],
    sortable: TrueFn,
    sortComparator: (a: number, b: number) => a - b
  })
];

const tableModel = TableFactory.createTableModel({
  rows: orders,
  columnDefs,
  fixedLeftColumnCount: 1                              // "ID" stays visible while scrolling
});

Fixed columns are part of the model, not of the column: fixedLeftColumnCount and fixedRightColumnCount in CreateTableModelPara (chapter 18 (Fixed columns)).

Table options

TableOptions holds the behaviour and look of a table. Start from the defaults and change only what you need:

import { TableOptions, TableOptionsIf } from "@guiexpert/table";

const tableOptions: TableOptionsIf = {
  ...new TableOptions(),                               // all defaults …
  hoverColumnVisible: false,                           // … and only what you change
  columnsResizable: true,
  columnsDraggable: true,
  defaultRowHeights: { header: 34, body: 34, footer: 0 }
};

Every option with its default value: TableOptionsIf. Walkthrough: chapter 19 (TableOptions).

TableApi and events

After the first render you receive a TableApi – from tableScope.getApi() or the tableReady event of a wrapper. It is the interface for everything you do with an existing table:

Data flow: filter, sort, display

Filtering and sorting do not change your data. The body model keeps all rows and derives the displayed rows from them; footer totals, clipboard and Excel export work on exactly these displayed rows.

Events

In plain TypeScript, pass an EventListenerIf to the TableScope – usually a subclass of EventAdapter that overrides only the methods you need. The wrappers forward the same events as outputs, props or CustomEvents:

import { EventAdapter, GeMouseEvent, SelectionModelIf } from "@guiexpert/table";

class OrderTableEvents extends EventAdapter {
  override onMouseClicked(evt: GeMouseEvent): void {
    if (evt.areaIdent === "body" && evt.clickCount === 2) {
      console.info("open the order in row", evt.rowIndex);
    }
  }

  override onSelectionChanged(model: SelectionModelIf): void {
    console.info("selected ranges", model.getRanges());
  }
}

Features at a glance

Each feature is built from the concepts above – model, column definitions, options, API and events. The training covers each one in a chapter of its own, with a live demo.

Styling and theming

All colours of the table are CSS variables with the prefix --ge-table-. The classes of the rendered elements only reference these variables, so a theme is a set of variable values – no selectors to override, no build step. main.css contains a light and a dark set; the table follows the data-theme attribute of the <html> element.

Your own theme

Override the variables in a stylesheet that is loaded after main.css. CSS variables are inherited: put them on html to theme every table, or on a class around one table to theme only that one.

/* light theme (default) */
.brand-table {
  --ge-table-header-center-bg: #1e293b;
  --ge-table-header-center-text: #f8fafc;
  --ge-table-body-center-text: #0f172a;    /* the body text follows the header text by default */
  --ge-table-row-even-bg: #f8fafc;          /* zebra rows */
  --ge-table-hover-row-bg: rgba(54, 187, 108, 0.12);
  --ge-table-body-center-selected-range-bg: rgba(54, 187, 108, 0.25);
}

/* dark theme */
html[data-theme="dark"] .brand-table {
  --ge-table-header-center-bg: #0b1220;
  --ge-table-body-center-text: #e2e8f0;
  --ge-table-row-even-bg: rgba(148, 163, 184, 0.06);
}

Light, dark and the system setting

Most applications offer light, dark and “follow the system”. Set data-theme in an inline script before the first paint, so that the page does not flash in the wrong theme:

<script>
  const root = document.documentElement;
  const system = matchMedia("(prefers-color-scheme: dark)");
  const systemTheme = () => (system.matches ? "dark" : "light");

  // saved choice ("light" | "dark") or, without one, the system setting
  root.dataset.theme = localStorage.getItem("theme") ?? systemTheme();
  system.addEventListener("change", () => {
    if (!localStorage.getItem("theme")) root.dataset.theme = systemTheme();
  });

  // e.g. from a toggle button
  function setTheme(theme) {
    root.dataset.theme = theme;
    localStorage.setItem("theme", theme);
  }
</script>

The table switches with the attribute – no API call needed. Live example: chapter 28 (Theming & dark mode); several complete themes: showcase Look and feel.

CSS variables

124 variables, grouped by what they colour. Header, body and footer each have their own set per side (west, center, east); west and east default to the center values.

Source: table-color-vars.css. From TypeScript: CssVars.

CSS classes

The rendered elements carry stable class names. Use them for layout details that are not covered by a variable – and in tests. Every cell also has the attributes data-area, data-row-index and data-col-index.

Performance checklist

The table is fast by default. These points keep it fast with very large data and frequent updates:

• Constant row height. If all rows have the same height, return it from getConstantRowHeight() in your own models. The table then finds the first visible row by a division instead of a binary search over the row heights (which it uses for different heights since 1.1.97). The built-in models do this automatically.
• Stable model and options. Create them once; a new object rebuilds the table (see The four building blocks).
• Filter, don't rebuild. Use externalFilterFunction and externalFilterChanged() instead of a new model with fewer rows.
• Update cells, not tables. For changing values use updateCells() – only the changed cells that are visible are redrawn.
• Lazy values. getValueAt() and renderers are called for visible cells only. Compute expensive values there instead of preparing them for all rows.
• Clean up. Renderers that attach listeners or framework components return a cleanup function. Call destroy() before you remove a table you created with TableScope; the wrappers do it for you.

Measure it yourself: showcases Large dataset (2 million rows) and Render speed.

What is not built in

GuiExpert Table concentrates on rendering, models and interaction. Some things are deliberately left to the application, others are not available yet. The usual approach for each:

A checklist for planning your own table – and for deciding when another product fits better: chapter 34 (Checklist & finale).

Help and feedback

GuiExpert Table is MIT-licensed and free to use, also in commercial applications – details on the licence page.