Tabs API Reference

API reference › The tabbed grid

All 26 pages Everything on one page → Developer guide →

The tabbed grid

modules/tabs is an opt-in top-of-grid tab strip where each tab is its own full, independently-configured grid instance - "configure each tab as per a normal grid" rather than one grid whose state is swapped. That is a deliberate rejection of the cheaper alternative: grid.state.get()/.apply() only repositions, hides, resizes and sorts existing columns by id (no field, type, editor or row data), so a state-swap only works when every tab shares one column schema and one source - strictly less than the ask. A tab may instead declare from: '<tabId>' plus a narrowing (where, group, join, …), and the module wires a source: { mode: 'derived', from: <the parent tab's live grid>, … } for it - the shipped derived-source mechanism, not a new config-inheritance one. createGrid is injected (the same pattern the React/Vue/Svelte adapters use), so the module imports no engine code regardless of how it is loaded - its own minified ESM build (tabs.esm.min.js) is about 12KB gzipped - the module and nothing else. A module bundle carries its own code plus a small shared runtime, not the engine: the framework adapters are 3-11KB, the KPI module about 50KB, while a module that inlines the whole engine (the web component, htmx) ships at roughly 760KB.

import { createGrid } from '@toclocoinc/lattice-grid';
import { createTabs } from '@toclocoinc/lattice-grid/modules/tabs';

const tabs = createTabs(document.querySelector('#tabs'), {
  createGrid,                     // injected -- see below
  createHeadlessGrid,             // optional: lets an unvisited tab still carry a count
  tabs: [
    { id: 'all', label: 'All', config: { rowKey: 'id', rows, columns } },
    { id: 'open', label: 'Open', from: 'all', where: (r) => r.stage === 'Open',
      follow: 'filtered', refresh: 'live', config: { columns } },
    { id: 'breached', label: 'Breached', from: 'open',       // derives from Open, not All -- a chain
      where: (r) => r.daysOverdue > 0, config: { columns },
      icon: '⚠️', badge: true,                          // "Breached 14" -- and it follows Open's filter
      badgeTone: (count) => (count > 0 ? 'bad' : 'good') },
  ],
  onBeforeTabChange: ({ id }) => !hasUnsavedEdit(),  // veto a switch
});

Lifecycle. A tab's grid mounts on first activation, not up front, and then stays alive - hidden, never destroyed - until the whole strip is. Per-tab scroll, selection, filters, sort, grouping, expansion - and an open cell/row editor - therefore survive a switch away and back natively, by simply not touching that grid instance, rather than through a lossy serialise/restore round-trip: leave a tab mid-edit, switch away, switch back, and the editor is exactly as it was left, uncommitted and undiscarded. Activating a derived tab materialises its whole ancestor chain first (mounted, hidden), and a cyclic from graph is refused - naming the exact cycle - when createTabs is called, not at first click.

A hidden tab costs nothing this module can spend. An inactive panel carries the hidden attribute (display:none); the module runs no timer, observer or repaint of its own against it. Measured with a real browser (bench/tabs-idle.mjs): several mounted-but-hidden, untouched tabs cost the same idle CPU as none at all. The one honestly-reported exception is not this module's: a derived tab's row model still re-derives on every change to its (possibly hidden) parent - by design, so reactivating it is instant rather than a stale flash - and the engine's own repaint listener for a derived source's rows:changed calls the renderer directly, bypassing grid.updates.pause() (which only holds the streaming-ingestion path). A hidden derived tab therefore still runs a read/compute/write pass on every parent change, even though the write phase paints a zero-size viewport; the bench measures and reports the size of that gap rather than leaving it inferred.

A tab can say what is waiting on it. badge: true puts that tab's own live row count on it - and for a derived tab the count follows, so filtering the parent restates the child's badge with it. A number or a string is a static badge; a function is handed the live count and returns what to show (null hides it). The tone is declared, never inferred from a threshold this module would have had to invent: badgeTone takes good, warn, bad or unknown - the same vocabulary a statistic tile grades to, so one data-tone rule in a theme dresses both - or a function of the count. icon adds a leading glyph: a single character or emoji, or an element you built. Never a markup string; nothing in this module parses HTML, and anything it cannot use is warned about once and ignored rather than coerced. Badges are off by default, and a tab that asks for none renders exactly the DOM it did before.

A tab nobody has clicked can still carry a count. Tabs mount lazily, so the tab most worth badging - the one you want to glance at - is precisely the one with no grid behind it. Inject the optional createHeadlessGrid, the same way createGrid is already injected and for the same reason, and an unactivated tab's count is computed with no element and no renderer, correct from first paint and still following its parent's filter. Leave it out and nothing breaks: that tab simply shows no badge until it is first activated, and the module says so once, naming the option. When the strip is narrow it is the label that gives way - it ellipsises while the count and the icon stay whole - and the strip still wraps rather than growing a scroll affordance.

A tab body does not have to be a grid. Give a tab a view - the factory that mounts its body, called as (el, config) => instance - and the tab hosts a kanban board, a KPI strip or a Gantt instead. createKanban and createKPI already have that signature, so they are passed straight in; the Gantt takes a single options object and mounts itself when given an element, so it is adapted in a line: view: (el, config) => createGantt({ ...config, element: el }). The factory is injected, never imported, for the same reason createGrid is. Such a tab's config is that viewer's own config.

{ id: 'board', label: 'Board', from: 'open',       // derives from the Open tab
  where: (r) => r.owner === me, follow: 'filtered', refresh: 'live',
  view: createKanban, badge: true,
  config: { rowKey: 'id', columnProperty: 'stage' } }

And it derives exactly as a grid tab does. That is the point rather than a bonus: from plus the same narrowing (where, group, join, follow, …) applies to a board or a KPI strip just as it does to a grid, so filtering the parent tab restates the board beside it. The mechanism is the derived source you already have: for a non-grid body the module materialises a headless grid carrying that same derived source and pipes its rows into the viewer through rows.apply({ add, update, remove }) - the keyed diff the grid, the board, the KPI panel and the Gantt all already accept from a Data Router. Nothing new is invented, the viewer stays unaware it is in a tab, and the module still imports no engine code. Deriving into a viewer therefore needs createHeadlessGrid injected alongside createGrid; without it the body mounts with its own rows and follows nothing, and the module says so once. A view tab with no from simply holds its own rows.

A body you have never opened is complete the moment you open it. Tabs mount lazily, so a board first shown after its parent has been filtered twice has a lot to catch up on - and because the headless grid holds the rows, there is no feed to join late: the body is seeded with the current set at mount and agrees exactly with a sibling that was mounted earlier. A count badge works on all three the same way, so a Gantt tab can read "Plan 14" as readily as a grid tab.

Accessibility. A real role="tablist"/"tab"/"tabpanel" with aria-selected and a roving tabindex, imitating the grid's own column-header keyboard model rather than the tool panel's tablist (which has the roles but no arrow-key handling). This is manual activation: ←/→ and Home/End move the roving tab stop without switching the panel or mounting a grid; Enter/Space, or a click, activates. The newly active tab's label is announced through a polite live region.

All / Open / Breached, a two-deep derivation chain, executed

createTabs deliberately has no headless mode - it requires a real host element, the same way createGrid itself does - so this executed example reaches for the same in-tree DOM test double the suite itself runs the renderer against headlessly (packages/dom/src/renderer/testdom.js), rather than a real browser. demo/tabs.html is the browser version of the same chain, with buttons that edit All directly and let Open and Breached follow.

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { root } = createTestDom();
const { createGrid } = await import('../packages/dom/src/index.js');
const { createTabs } = await import('../packages/modules/tabs/index.js');

const rows = [
  { id: 1, stage: 'Open', daysOverdue: 0 },
  { id: 2, stage: 'Open', daysOverdue: 5 },
  { id: 3, stage: 'Won', daysOverdue: 0 },
  { id: 4, stage: 'Open', daysOverdue: 2 },
];
const columns = [{ field: 'id' }, { field: 'stage' }, { field: 'daysOverdue' }];

const tabs = createTabs(root, {
  createGrid,
  tabs: [
    { id: 'all', label: 'All', config: { rowKey: 'id', rows, columns } },
    { id: 'open', label: 'Open', from: 'all', where: (r) => r.stage === 'Open', config: { columns } },
    // derives from Open, not All -- a two-deep chain
    { id: 'breached', label: 'Breached', from: 'open', where: (r) => r.daysOverdue > 0, config: { columns } },
  ],
});

tabs.activate('breached');                    // materialises 'open' too, automatically
const counts = ['all', 'open', 'breached'].map((id) => tabs.tab(id).rows.count());
tabs.destroy();
return counts.join(',');                       // 4,3,2

Opening on a chosen tab, and vetoing a switch, executed

active picks the tab the strip opens on rather than the first; the three config callbacks are sugar for the same events on() exposes, so onBeforeTabChange can veto a switch with preventDefault(reason) and onTabChangeCancelled is told why. onTabChange fires only for a switch that actually happened - note it does not fire for the initial tab.

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { root } = createTestDom();
const { createGrid } = await import('../packages/dom/src/index.js');
const { createTabs } = await import('../packages/modules/tabs/index.js');

const rows = [{ id: 1 }];
const columns = [{ field: 'id' }];
const log = [];

const tabs = createTabs(root, {
  createGrid,
  active: 'review',                             // open here, not on the first tab
  tabs: [
    { id: 'draft', label: 'Draft', config: { rowKey: 'id', rows, columns } },
    { id: 'review', label: 'Review', config: { rowKey: 'id', rows, columns } },
    { id: 'locked', label: 'Locked', config: { rowKey: 'id', rows, columns } },
  ],
  onTabChange: (e) => log.push(`changed:${e.id}`),
  onBeforeTabChange: (e) => { if (e.id === 'locked') e.preventDefault('sealed'); },
  onTabChangeCancelled: (e) => log.push(`cancelled:${e.id}(${e.reason})`),
});

const opened = tabs.activeId;                   // 'review' -- config.active won
tabs.activate('draft');                         // allowed, so onTabChange fires
tabs.activate('locked');                        // vetoed, so onTabChangeCancelled fires
const ended = tabs.activeId;                    // still 'draft'
tabs.destroy();
return `${opened} | ${log.join('; ')} | ${ended}`;

A tab nobody has clicked, carrying a live count, executed

A badge needs rows, and rows normally need a mounted grid - so a tab that has never been activated would have nothing to count. Injecting createHeadlessGrid alongside createGrid gives that tab a real, derived count with no DOM and no mount. Without it the tab below shows no badge at all until its first activation, and the module says so once.

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { root } = createTestDom();
const { createGrid } = await import('../packages/dom/src/index.js');
const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createTabs } = await import('../packages/modules/tabs/index.js');

const rows = [
  { id: 1, stage: 'Open', daysOverdue: 0 },
  { id: 2, stage: 'Open', daysOverdue: 5 },
  { id: 3, stage: 'Won', daysOverdue: 0 },
  { id: 4, stage: 'Open', daysOverdue: 2 },
];
const columns = [{ field: 'id' }, { field: 'stage' }, { field: 'daysOverdue', type: 'number' }];

const tabs = createTabs(root, {
  createGrid,
  createHeadlessGrid,                           // what gives an unmounted tab a count
  tabs: [
    { id: 'all', label: 'All', badge: true, config: { rowKey: 'id', rows, columns } },
    { id: 'breached', label: 'Breached', from: 'all', where: (r) => r.daysOverdue > 0,
      follow: 'filtered', refresh: 'live', badge: true, config: { columns } },
  ],
});

// 'breached' has never been activated, so it has no grid of its own.
const button = root.querySelectorAll('[role=tab]')
  .find((b) => b.getAttribute('data-tab-id') === 'breached');
const badge = button.children
  .find((c) => String(c.className || '').includes('lat-tabs__badge'));
const state = tabs.isMounted('breached') ? 'mounted' : 'unmounted';
const text = String(badge.textContent).trim().replace(/\s+/g, ' ');
tabs.destroy();
return `${state} | ${text}`;                     // unmounted | 2 rows

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The tabs module

TabDescriptor

TabChangeEvent

`beforeTabChange`: a switch is about to be applied, and may be refused. Delivered through `packages/modules/shared/emitter.js`'s `emitBefore`, which builds the event from the module's action context plus `type`, the resolved `origin` and the veto surface - so every member below is always present on this event. A handler refuses the switch by calling `preventDefault(reason?)` or by returning a Promise that resolves `false`; the active tab then does not change and `tabChange:cancelled` fires carrying the reason.

TabChangedEvent

`tab:changed`: the switch happened - the target panel is revealed, its grid materialised on first activation, the badges refreshed and `aria-selected` moved. A notification, so it carries no `preventDefault`.

TabChangeCancelledEvent

`tabChange:cancelled`: a `beforeTabChange` handler refused the switch, so the active tab did not change. A notification, so it carries no `preventDefault`.

TabsEventPayloads

What a handler receives, per tabs event.

TabsConfig

Tabbed-grid configuration. The tab strip inherits as below, and so does every grid it mounts unless that tab's own `config.theme` says otherwise. Theme: no `theme` of its own - it inherits. Its colours are the grid's `--lattice-*` tokens, so `data-theme="dark"` on any ancestor (a layout's `theme: 'dark'`, or `<html>`) darkens it with everything else, and the nearest `data-theme` wins. Load the grid stylesheet, which carries the tokens.

Tabs

A tabbed grid: a `role="tablist"` strip above a stack of `role="tabpanel"` regions, each hosting its own, independently-configured grid instance. A tab's grid mounts on first activation and is kept alive, hidden, until `destroy()`.

Properties

Methods

Events