v1.6.0

<bmx-data-grid>

A data grid for business applications: a million rows scroll as smoothly as a hundred, with fifty column types, sorting, filtering, grouping with totals, and editing that writes straight into the data - usable from any framework, or from plain HTML with no framework at all.

61 properties · 24 events · 51 methods · 22 parts

Example

Group by team Show changes Pivot by team Export CSV
Everything is live. Click a heading to sort, drag it to the group bar, type in the search, double-click or start typing to edit a cell (salaries cannot go below zero), and press Ctrl+Z to undo. Choose rows with the boxes, open a row with its expander, and right-click a cell for its commands.
Spreadsheet mode Export to Excel
A worksheet in a grid. Columns have letters and rows numbers (the titles are row 1). Type = in any cell for a formula, then click or drag over cells to put their references in - each is outlined in its colour - or edit the active cell in the formula bar above. Amount is a formula column (=[@Price]*[@Qty]*(1-[@Discount])); the totals, sorting and the Excel export use the values, and the export keeps the formulas.
Show markup
<div class="row" role="group" aria-label="Example actions">
  <bmx-button id="ex-dg-group" variant="soft">Group by team</bmx-button>
  <bmx-button id="ex-dg-changes" variant="soft">Show changes</bmx-button>
  <bmx-button id="ex-dg-pivot" toggle variant="soft">Pivot by team</bmx-button>
  <bmx-button id="ex-dg-csv" variant="ghost">Export CSV</bmx-button>
</div>

<bmx-data-grid id="ex-dg" label="People" checkboxes style="--bmx-data-grid-height: 26rem; margin-block-start: 1rem"></bmx-data-grid>

<div class="row" style="margin-block-start: 1rem">
  <span class="note" id="ex-dg-out">
    <strong>Everything is live.</strong> Click a heading to sort, drag it to the group bar, type in the search,
    double-click or start typing to edit a cell (salaries cannot go below zero), and press <kbd>Ctrl</kbd>+<kbd>Z</kbd>
    to undo. Choose rows with the boxes, open a row with its expander, and right-click a cell for its commands.
  </span>
</div>

<script type="module">
  await customElements.whenDefined('bmx-data-grid');

  const grid = document.getElementById('ex-dg');
  const out = document.getElementById('ex-dg-out');

  // Columns are plain data: a field, a type and a few options.
  grid.columns = [
    { field: 'name', type: 'person', subtitleField: 'role', width: 220, pinned: 'start' },
    { field: 'team', type: 'select', options: ['Platform', 'Payments', 'Mobile', 'Data'] },
    { field: 'status', type: 'status' },
    { field: 'salary', type: 'currency', currency: 'GBP', min: 0, aggregate: 'sum' },
    { field: 'started', type: 'date' },
    { field: 'progress', type: 'progress', title: 'Goals' },
    { field: 'rating', type: 'rating' },
    { field: 'remote', type: 'toggle' },
  ];

  const names = ['Ada Lovelace', 'Grace Hopper', 'Alan Turing', 'Katherine Johnson', 'Margaret Hamilton', 'Barbara Liskov', 'Radia Perlman', 'Sophie Wilson'];
  const teams = ['Platform', 'Payments', 'Mobile', 'Data'];
  grid.rows = Array.from({ length: 200 }, (_, i) => ({
    id: i + 1,
    name: names[i % names.length],
    role: ['Architect', 'Analyst', 'Engineer', 'Lead'][i % 4],
    team: teams[i % 4],
    status: ['Active', 'On leave', 'Active', 'Pending'][i % 4],
    salary: 42000 + ((i * 7919) % 60000),
    started: `20${String(15 + (i % 11)).padStart(2, '0')}-0${(i % 9) + 1}-15`,
    progress: (i * 37) % 101,
    rating: (i % 5) + 1,
    remote: i % 3 === 0,
  }));

  document.getElementById('ex-dg-group').addEventListener('click', () => grid.setGroupBy(['team']));
  document.getElementById('ex-dg-changes').addEventListener('click', async () => {
    const { added, updated, removed } = await grid.getChanges();
    out.textContent = `getChanges() - ${added.length} added, ${updated.length} changed, ${removed.length} removed`;
  });
  document.getElementById('ex-dg-csv').addEventListener('click', () => grid.download('csv'));
  document.getElementById('ex-dg-pivot').addEventListener('bmxActivate', event =>
    grid.setPivot(event.detail.pressed ? { rows: ['team'], columns: ['status'], values: [{ field: 'salary', aggregate: 'avg' }] } : null),
  );

  // Rules as data: the filters' own tests, so they can be kept on a server.
  grid.formatRules = [{ field: 'salary', when: { op: 'gte', value: 95000 }, style: { tone: 'success', bold: true } }];

  // A panel under each row, opened with its expander.
  grid.detailRenderer = (row, panel) => {
    panel.style.padding = '0.75rem 1rem';
    return `${row.name} has been in ${row.team} since ${row.started}, working ${row.remote ? 'remotely' : 'from the office'}.`;
  };
  grid.detailHeight = 90;

  // Events: the data changed, and which rows are chosen.
  grid.addEventListener('bmxGridDataChange', event => {
    const cell = event.detail.cells[0];
    if (cell) out.textContent = `bmxGridDataChange - ${cell.field}: ${JSON.stringify(cell.oldValue)} -> ${JSON.stringify(cell.value)}`;
  });
  grid.addEventListener('bmxGridSelectionChange', event => {
    out.textContent = `bmxGridSelectionChange - ${event.detail.count} rows chosen`;
  });

  // Rows from a server instead: grid.dataProvider = async ({ start, count, sort, filters, search }) => ({ rows, total });
</script>

<div class="row" role="group" aria-label="Spreadsheet example actions" style="margin-block-start: 2rem">
  <strong>Spreadsheet mode</strong>
  <bmx-button id="ex-dg-xlsx" variant="ghost">Export to Excel</bmx-button>
</div>

<bmx-formula-bar id="ex-dg-bar" engine="ex-dg-sheet" label="Formula for the active cell" style="margin-block-start: 0.75rem"></bmx-formula-bar>
<bmx-data-grid id="ex-dg-sheet" spreadsheet group-panel="false" label="Quote" sheet-name="Quote" style="--bmx-data-grid-height: 24rem; margin-block-start: 0.5rem"></bmx-data-grid>

<div class="row" style="margin-block-start: 1rem">
  <span class="note">
    <strong>A worksheet in a grid.</strong> Columns have letters and rows numbers (the titles are row 1). Type
    <code>=</code> in any cell for a formula, then click or drag over cells to put their references in - each is
    outlined in its colour - or edit the active cell in the formula bar above. <em>Amount</em> is a formula column
    (<code>=[@Price]*[@Qty]*(1-[@Discount])</code>); the totals, sorting and the Excel export use the values, and the
    export keeps the formulas.
  </span>
</div>

<script type="module">
  await customElements.whenDefined('bmx-data-grid');
  const sheet = document.getElementById('ex-dg-sheet');

  sheet.columns = [
    { field: 'item', title: 'Item', width: 200 },
    { field: 'price', title: 'Price', type: 'currency', currency: 'GBP' },
    { field: 'qty', title: 'Qty', type: 'integer', aggregate: 'sum' },
    { field: 'discount', title: 'Discount', type: 'percent', width: 130 },
    { field: 'amount', title: 'Amount', type: 'currency', currency: 'GBP', aggregate: 'sum', formula: '=[@Price]*[@Qty]*(1-[@Discount])' },
  ];
  // Formulas typed into cells live in the rows, as text starting with `=`.
  sheet.rows = [
    { item: 'Standing desk', price: 420, qty: 6, discount: '=IF(C2>=5, 10%, 0)' },
    { item: 'Monitor arm', price: 85, qty: 12, discount: '=IF(C3>=10, 15%, 0)' },
    { item: 'Task chair', price: 310, qty: 6, discount: '=D2' },
    { item: 'Cable tray', price: 24, qty: '=C2+C4', discount: 0 },
    { item: 'Delivery', price: '=ROUNDUP(SUM(B2:B5)*2%, -1)', qty: 1, discount: 0 },
  ];

  document.getElementById('ex-dg-xlsx').addEventListener('click', () => sheet.download('xlsx'));
</script>

DATA

Bind an array to rows, point src at JSON, JSON lines or CSV, give it a <table> of your own HTML to read, or set dataProvider to fetch rows from your server a block at a time with the sort, filters and search - for data too large to send to the page. Columns are read from the data when you give none.

COLUMNS

Fifty column types, from text, numbers, money and dates to status badges, progress bars, rings, star ratings, heat maps, data bars, trends, sparklines, avatars, images, tags, colours, files, due dates, buttons and row actions - each formatted in the reader's locale, sorted by its value rather than its text, filtered in its own way and edited with a fitting editor. Resize, move, pin to either side, hide, and group headings into bands.

FINDING

Click a heading to sort, Shift+click to sort by more columns. The quick search finds rows with every word and highlights them; the filter row takes >100, 10..20, 2026-09, last 7 days, =exact, !not; each column's menu filters by a list of its values with counts. Drag a heading to the group bar to group by it, as deep as you like, with totals in every group row and the footer.

EDITING

Editable unless readonly is set. Type over a cell, press Enter or F2, or double-click; Tab and Enter move on. Every edit is validated, can be refused by the page through a cancelable event, and is undone with Ctrl+Z. Paste a block from a spreadsheet, copy a range out, clear it with Delete. getChanges() gives what was added, changed and removed since the data was loaded, for saving.

FORMULAS

A column's formula works out every row, as a spreadsheet's calculated column does: =[@Price]*[@Qty], with over four hundred Excel functions. spreadsheet turns the grid into a worksheet: lettered columns, numbered rows (the titles are row 1), and formulas typed into any editable cell - =B2*C2, =SUM(D2:D20) - with references put in by clicking or dragging over cells and outlined in their colours. Copy, paste and the fill handle move formulas as a spreadsheet does, and rows added or removed carry their references with them. The grid shows, sorts, filters, totals and exports values; its Excel export is the sheet itself, formulas and all. A bmx-formula-bar given the grid as its engine edits the active cell, and formula-engine puts the grid's sheet in a page's bmx-formula-engine, so formulas there and here can use each other.

TREES AND DETAIL

Rows that hold rows, nested (treeField) or naming their parent (parentField): each level sorts among itself, and a filter keeps a match together with every row above it. A row can open a panel of its own - a grid of its lines (detailGrid) or anything detailRenderer draws.

WORKING IN IT

Drag the corner of the chosen cells to fill a series on, as a spreadsheet does; Ctrl+D and Ctrl+R fill down and across. Drag rows by their handle into a new order (rowReorder). Right-click a cell for its commands, and add your own. Pin rows to the top, freeze the first lines, span a cell across its neighbours, and style cells and rows by rules written as data (formatRules). After a save, undo still steps back.

PIVOT, CARDS, PAGES, PRINT

Pivot the rows into totals (pivot, or the reader's own with allowPivot). Narrow grids show each row as a card. pagination pages instead of scrolling. Print what is shown, headings on every page, or save an Excel file in the grid's own colours with groups as outline levels.

LIVE

liveSrc takes a WebSocket or server-sent events URL whose messages add, update and remove rows, reconnecting when the connection drops.

LOOKS

Six appearances - modern, striped, bordered, minimal, glass and cards - three densities, and every colour from the theme, with themed scrollbars. Changed cells flash as live data updates them.

ACCESSIBLE

A grid (a treegrid when grouped or a tree) with every row and column numbered for screen readers even though only those in view exist. The keyboard reaches everything - cells, headings, the filter row, menus, editing, selection - and changes are announced.

Properties

PropertyAttributeTypeDefaultDescription
allowPivot allow-pivot boolean false A Pivot button in the toolbar, so the reader can pivot the rows themselves.
appearance appearance BmxGridAppearance 'modern' The look: modern, striped, bordered, minimal, glass or cards.
blockSize block-size number 100 Rows fetched per request from dataProvider.
cardBreakpoint card-breakpoint number 600 The width in pixels below which presentation="auto" shows cards.
cardFields card-fields string | string[] — The fields a card shows, separated by spaces; the first is the card's title. Default: the first six columns shown.
checkboxes checkboxes boolean false Show a checkbox column for choosing rows.
columnMenu column-menu boolean true Each heading's menu: sort, filter, group, pin, hide.
columns columns BmxGridColumn[] | string [] The columns: { field, title?, type?, ... }, or JSON in the attribute. Read from the data when empty.
contextMenu context-menu boolean true The menu on a right-click, Shift+F10 or the menu key over a cell.
contextMenuItems property only BmxGridMenuItem[] | ((context: BmxGridMenuContext) => BmxGridMenuItem[]) — Your own commands for that menu, after the grid's: a list of { id, label, icon?, disabled?, separator? }, or a function of the cell and rows that returns one. The choice arrives as bmxGridMenuAction.
dataProvider property only BmxGridDataProvider — Rows from your server, a block at a time: called with { start, count, sort, filters, search, signal }, answers { rows, total }. The sort, filters and search are then the server's to apply. Set from script.
density density BmxGridDensity 'standard' Row height: compact, standard or comfortable.
detailGrid detail-grid BmxGridDetailGrid | string — A grid of a row's own rows in its panel: { field, columns, readonly? }, or JSON.
detailHeight detail-height number 260 The height of a row's detail panel, in pixels.
detailRenderer property only (row: BmxGridRow, container: HTMLElement) => string | Node | void — Fills the panel under a row opened with its expander: return text or a node, or fill container yourself. Set from script.
emptyText empty-text string — What to say when there are no rows.
enterMoves enter-moves 'down' | 'right' | 'none' 'down' Where Enter goes after an edit: down, right or none.
fileName file-name string 'data' The name exported files are saved under.
fillHandle fill-handle boolean true Drag the corner of the chosen cells to fill on down or across, as a spreadsheet does.
filterRow filter-row boolean false Show a row of filters under the headings.
filters filters BmxGridFilter[] | string [] Column filters: [{ field, op, value }], or JSON.
flashChanges flash-changes boolean true Flash cells that updateRows changes.
footer footer boolean true Show the totals row, when any column has an aggregate.
formatRules format-rules BmxGridFormatRule[] | string [] Conditional formatting as data: [{ field, when: { op, value }, style: { tone, bold } }], or JSON.
formulaEngine formula-engine string — A bmx-formula-engine (its id, or a selector) whose workbook holds the grid's sheet, so formulas on the page and in the grid can use each other: =Rates!B2 here, =SUM(Data[Amount]) there. Default: a workbook of the grid's own.
frozenRows frozen-rows number 0 Rows kept at the top whatever the scroll: the first this many lines.
groupBy group-by string | string[] '' Fields to group by, outermost first: "region status" or a list.
groupPanel group-panel boolean true Show the bar that headings are dragged to, to group by them.
groupsExpanded groups-expanded boolean true Groups start open.
label label string — The accessible name. Default: "Data".
liveSrc live-src string — A WebSocket (ws:, wss:) or server-sent events URL whose messages update rows.
liveType live-type 'auto' | 'websocket' | 'sse' 'auto' What liveSrc is. auto goes by the URL's scheme.
loading loading boolean false Show a loading bar. Set while your own data is on its way.
locale locale string — A BCP 47 locale for numbers, money and dates. Default: the page's lang, then the reader's.
page page number 1 The page on show, from 1.
pageSize page-size number 50 Rows on a page.
pagination pagination boolean false Show rows a page at a time, with a pager, instead of one long scroll.
parentField parent-field string — Tree data, flat: the field holding each row's parent's key (by rowKey).
pinnedRows pinned-rows unknown[] | string [] Rows pinned at the top, by key: they stay in view as the rest scroll.
pivot pivot BmxGridPivot | string — Pivot the rows: { rows: [...], columns: [...], values: [{ field, aggregate }] }, or JSON. Empty for the rows as they are.
presentation presentation 'auto' | 'table' | 'cards' 'auto' table, cards (one card per row, for small screens), or auto: cards when the grid is narrower than cardBreakpoint.
rangeSelection range-selection boolean true Choose rectangles of cells with Shift and the mouse: to copy, paste over, clear and total.
readonly readonly boolean false Nothing can be edited, added or removed. The grid is editable by default.
requestInit property only RequestInit — Options for fetching src: headers, credentials.
rowKey row-key string 'id' The field that identifies a row, for selection, updates and changes. Rows without it are known by themselves.
rowNumbers row-numbers boolean false Show a column of row numbers.
rowReorder row-reorder boolean false Rows are moved by dragging their handle, or with Alt+Shift and the up and down arrows.
rowSelection row-selection 'none' | 'single' | 'multiple' 'multiple' How rows are chosen: none, single or multiple.
rows rows BmxGridRow[] | string [] The rows: an array of objects, or JSON in the attribute. Edits are written into these objects.
search search string '' The quick search: rows with every word, in any column.
sheetName sheet-name string 'Data' The name of the grid's sheet in its workbook, and of the table its rows make (Data[Amount]).
sort sort string | BmxGridSort[] '' Sort keys: "region total:desc", or [{ field, direction }].
spreadsheet spreadsheet boolean false Spreadsheet mode: columns get letters and rows numbers, as on a worksheet - the titles are row 1, so the first row is row 2 - and any editable cell takes a formula typed with =: =B2*C2, =SUM(D2:D20), =[@Price]*1.2. The row keeps the formula; the grid shows, sorts, filters, totals and exports its value, and the Excel export carries the formulas. Clicking cells while a formula is typed puts references in, each outlined in its colour. A bmx-formula-bar given the grid as its engine edits the active cell.
src src string — A URL to load the rows from: JSON, JSON lines, CSV or TSV.
stateKey state-key string — A name to keep the reader's view under in this browser: sort, filters, columns, grouping.
statusBar status-bar boolean true Show the counts, the changes and the totals of the chosen cells under the grid.
timeZone time-zone string — An IANA zone for times, or utc. Default: the reader's.
toolbar toolbar boolean true Show the toolbar: search, columns, grouping, export, undo.
treeColumn tree-column string — The column that shows the tree's branches. Default: the first column of data.
treeExpanded tree-expanded boolean false Tree rows start open.
treeField tree-field string — Tree data, nested: the field holding each row's children.

Events

EventDetailDescription
bmxGridActiveCellChange BmxGridActiveCellDetail The active cell moved.
bmxGridCellAction BmxGridCellActionDetail A cell's button was pressed.
bmxGridCellChange BmxGridCellChangeDetail A cell is about to change: by an edit, a paste, a clear, undo or redo. Cancelable.
bmxGridCellPress BmxGridCellPressDetail Spreadsheet mode: a cell was pressed, or dragged on from. Cancel it to take the press - a formula bar does, to put references in its formula.
bmxGridColumnChange BmxGridColumnChangeDetail Columns were resized, moved, pinned, hidden or shown.
bmxGridConnection BmxGridConnectionDetail The live connection opened, dropped, is being tried again, or closed.
bmxGridContextMenu BmxGridMenuContext The context menu is about to open. Cancel to show your own instead.
bmxGridDataChange BmxGridDataChangeDetail The data changed. One event per gesture: a paste of a hundred cells is one.
bmxGridDetailEvent BmxGridDetailEventDetail Something happened in a detail panel's grid: its event, carried out.
bmxGridDetailToggle BmxGridDetailToggleDetail A row's detail panel opened or closed.
bmxGridEditStart BmxGridEditStartDetail An edit is about to start. Cancelable.
bmxGridFilterChange BmxGridFilterChangeDetail The filters or the search changed.
bmxGridGroupChange BmxGridGroupChangeDetail The grouping changed.
bmxGridLoad BmxGridLoadDetail Rows arrived from src, a file or the provider, or loading failed.
bmxGridMenuAction BmxGridMenuActionDetail A command of your own was chosen from the context menu.
bmxGridPageChange BmxGridPageChangeDetail The page on show changed.
bmxGridPivotChange BmxGridPivotChangeDetail The pivot changed.
bmxGridRowActivate BmxGridRowActivateDetail A row was opened.
bmxGridRowMove BmxGridRowMoveDetail A row is about to move. Cancelable.
bmxGridRowsRemove BmxGridRowsRemoveDetail Rows are about to be removed. Cancelable.
bmxGridSelectionChange BmxGridSelectionChangeDetail The chosen rows changed.
bmxGridSortChange BmxGridSortChangeDetail The sort changed.
bmxGridStateChange BmxGridStateChangeDetail The view changed: sort, filters, search, columns, grouping.
bmxGridTreeToggle BmxGridTreeToggleDetail A tree row opened or closed.

Methods

MethodSignatureDescription
acceptChanges acceptChanges(options?: { clearHistory?: boolean; }) => Promise<void> Treats the data as it is now as saved: nothing counts as changed any more. Undo and redo still work across the save, and whatever they change is then reported by getChanges for saving again; clearHistory forgets them as well.
addRow addRow(row?: BmxGridRow, index?: number, edit?: boolean) => Promise<BmxGridRow | null> Adds a row (an empty one by default) at a position among all rows, and returns it. With edit, it is scrolled to and its first editable cell opened.
applyLiveMessage applyLiveMessage(message: unknown) => Promise<void> Applies one message as if it had come from liveSrc: for a feed of your own (SignalR, socket.io, a worker) in the same shape - an array of rows, or { op: 'upsert' | 'remove' | 'replace', rows | row | keys } - as an object or its JSON text.
autosizeColumns autosizeColumns(fields?: readonly string[]) => Promise<void> Fits columns to their contents: these fields, or all.
clearFilters clearFilters() => Promise<void> Clears every filter and the search.
clearSelection clearSelection() => Promise<void> Chooses no rows.
collapseAll collapseAll() => Promise<void> Closes every group, or every tree row.
connectLive connectLive(url?: string, type?: "auto" | "websocket" | "sse") => Promise<void> Connects to a live source (default liveSrc) whose messages update rows.
disconnectLive disconnectLive() => Promise<void> Closes the live connection.
download download(format?: BmxGridExportFormat, options?: BmxGridExportOptions) => Promise<void> Exports and saves the file, named by fileName.
editCell editCell(rowOrKey: BmxGridRow | unknown, field: string) => Promise<boolean> Starts editing a cell. False when it cannot be edited.
expandAll expandAll() => Promise<void> Opens every group, or every tree row.
exportData exportData(format?: BmxGridExportFormat, options?: BmxGridExportOptions) => Promise<Blob> The rows on show as a file: xlsx, csv, tsv or json.
getCellAddress getCellAddress(rowOrKey?: BmxGridRow | unknown, field?: string) => Promise<string | null> A cell's sheet address (Data!B3), or the active cell's when no row is given. Null without formulas.
getChanges getChanges() => Promise<BmxGridChanges> What was added, changed and removed since the rows were loaded or the changes last accepted.
getFormulaWorkbook getFormulaWorkbook() => Promise<BmxFormulaWorkbook | null> The formula workbook the grid's sheet is on, while it has formulas (spreadsheet mode or formula columns): the grid's own, or the formulaEngine's. Null otherwise.
getPrintHtml getPrintHtml() => Promise<string> The printable document print() uses, as HTML: for a print preview of your own, or a PDF made on a server.
getRows getRows() => Promise<BmxGridRow[]> Every row, in the order given.
getSelectedRows getSelectedRows() => Promise<BmxGridRow[]> The chosen rows.
getShownRows getShownRows() => Promise<BmxGridRow[]> The rows kept by the filters and search, in the order shown.
getState getState() => Promise<BmxGridState> Everything the reader has changed about the view, to save and give back to setState.
goToCell goToCell(address: string) => Promise<boolean> Moves the active cell to a sheet address (B3, Data!B3) and shows it. False when the row is filtered out or the column hidden.
goToPage goToPage(page: number) => Promise<void> Shows a page, from 1, when pagination is on.
load load(source: string | URL | Blob) => Promise<void> Loads rows from a URL, a File or Blob (a chosen or dropped file), or text: JSON, JSON lines, CSV or TSV. Replaces the rows; columns are read from the data when none were given.
moveRow moveRow(rowOrKey: BmxGridRow | unknown, before: BmxGridRow | unknown | null) => Promise<boolean> Moves a row to before another (objects or keys), or to the end with null, as dragging its handle does. False when rows cannot move now.
openFile openFile() => Promise<void> Opens the browser's file picker to load a CSV, TSV or JSON file.
pinColumn pinColumn(field: string, side: "start" | "end" | null) => Promise<void> Pins a column to the start or end, or unpins it with null.
print print() => Promise<void> Opens the print dialog for the rows on show: the columns shown, every row the filters keep, groups open, headings on every page.
redo redo() => Promise<boolean> Does again what was undone.
refresh refresh() => Promise<void> Runs the sort, filters and grouping again: after changing rows in place. For a server source, asks again.
removeRows removeRows(rows: readonly (BmxGridRow | unknown)[]) => Promise<number> Removes rows, by the row objects or their keys. Returns how many went.
revertChanges revertChanges() => Promise<void> Puts back every change since the rows were loaded or the changes last accepted.
scrollToRow scrollToRow(rowOrKey: BmxGridRow | unknown, field?: string) => Promise<boolean> Scrolls to a row (the object, its key, or its position among the rows on show) and makes it active.
selectAll selectAll() => Promise<void> Chooses every row the filters keep.
selectRows selectRows(rows: readonly (BmxGridRow | unknown)[], add?: boolean) => Promise<void> Chooses rows, by the row objects or their keys; add keeps those already chosen.
setCellText setCellText(address: string, text: string) => Promise<boolean> Sets a cell, given by its sheet address, from text as a reader types it: read and checked as the cell's editor would, kept for undo and reported by the usual events. In spreadsheet mode, = starts a formula. False when the text is refused or there is no such editable cell.
setCellValue setCellValue(rowOrKey: BmxGridRow | unknown, field: string, value: unknown) => Promise<boolean> Sets one cell, as an edit would: validated, cancelable, undoable. False when refused.
setColumnHidden setColumnHidden(field: string, hidden: boolean) => Promise<void> Shows or hides a column.
setColumnWidth setColumnWidth(field: string, width: number) => Promise<void> Sets a column's width in pixels, as dragging its edge does.
setFilter setFilter(field: string, filter: Omit<BmxGridFilter, "field"> | null) => Promise<void> Sets a column's filter, or clears it with null.
setFocus setFocus() => Promise<void> Moves focus into the grid.
setGroupBy setGroupBy(fields: readonly string[]) => Promise<void> Groups by these fields, outermost first; an empty list stops grouping.
setPivot setPivot(pivot: BmxGridPivot | null) => Promise<void> Pivots the rows, or shows them as they are with null.
setState setState(state: BmxGridState | string) => Promise<boolean> Restores a view saved by getState (an object or its JSON). False when it could not be read.
showReferences showReferences(references?: readonly BmxGridReference[]) => Promise<void> Outlines references in spreadsheet mode, each in its colour - what a formula bar editing the grid's cells shows. An empty list clears them.
sortBy sortBy(field: string, direction?: "asc" | "desc" | null, add?: boolean) => Promise<void> Sorts by a column: asc, desc, or null to stop. add keeps the other sort keys.
stopEdit stopEdit(cancel?: boolean) => Promise<void> Closes the editor: commits the value, or with cancel keeps the old one.
toggleDetail toggleDetail(rowOrKey: BmxGridRow | unknown, open?: boolean) => Promise<boolean> Shows or hides a row's detail panel; toggles without open.
toggleRow toggleRow(rowOrKey: BmxGridRow | unknown, open?: boolean) => Promise<boolean> Opens or closes a tree row (the object or its key); toggles without open. False when it has no rows inside.
undo undo() => Promise<boolean> Undoes the last change. False when there is nothing to undo.
updateRows updateRows(rows: readonly BmxGridRow[]) => Promise<{ updated: number; added: number; }> Updates rows from newer copies, matched by rowKey: changed values are written in and flash (green up, red down for numbers). Rows with a new key are added at the end. For live data - prices, statuses, counters.

Slots

SlotDescription
(default) a <table> to read the columns and rows from.
empty what to show when there are no rows.
toolbar-end your own controls at the end of the toolbar.
toolbar-start your own controls at the start of the toolbar.

CSS shadow parts

PartDescription
clear-filters
context-menu
edit-error
empty
error
frame
grid
group-chip
group-panel
live-badge
loading
menu
menu-item
pager
pager-button
pager-size
pivot-panel
search
search-input
status
tool-button
toolbar

CSS custom properties

PropertyDescription
--bmx-data-grid-active The ring around the active cell.
--bmx-data-grid-background Behind the rows.
--bmx-data-grid-card-background A card, when rows are shown as cards. @part toolbar - the bar of tools above the grid. @part tool-button - a tool. @part search - the quick search. @part search-input - its field. @part group-panel - the bar headings are dragged to, to group by them. @part group-chip - a field the rows are grouped by. @part frame - the box around the grid. @part grid - the scrolling grid. @part header-row - the headings. @part header-band-row - the row of bands over grouped headings. @part header-band - one band. @part header-cell - one heading. @part header-menu - a heading's menu button. @part resizer - the edge dragged to resize a column. @part filter-row - the row of filters under the headings. @part filter-input - one filter. @part filter-button - a filter by a list of values. @part cell - a cell. Also cell-<type> (cell-currency, cell-status), cell-active, cell-dirty and cell-<tone> from cellTone. @part group-row - a group's heading. @part group-count - the number of rows in a group. @part footer-row - the totals. @part footer-cell - one total. @part badge - a status, badge, priority or choice. Also badge-<tone>. @part chip - a tag. @part bar - a progress bar, meter or data bar. @part rating - the stars. @part avatar - a person's picture or initials. @part image - a picture. @part swatch - a colour. @part timeline - a timespan's track. @part link - a link. @part checkbox - a checkbox. @part switch - a switch. @part cell-button - a cell's button. @part action - a row action. @part match - a search match. @part editor - the field a cell is edited in. @part edit-error - why an edit was refused. @part menu - a pop-up: a column's menu, the columns, export, row height, the context menu, the pivot panel. @part context-menu - the menu on a right-click over a cell. @part pivot-panel - the panel that pivots the rows. @part detail - a row's detail panel. @part card - a row shown as a card. @part fill-handle - the square at the corner of the chosen cells, dragged to fill. @part row-drop - where a dragged row would land. @part pager - the page controls. @part pager-button - one of them. @part pager-size - the rows-per-page choice. @part live-badge - the state of the live connection. @part menu-item - one of its commands. @part status - the counts under the grid. @part clear-filters - the button that clears every filter. @part empty - what is shown when there are no rows. @part error - what is shown when the rows could not be loaded. @part loading - the loading bar. @part column-letter - a column's letter in spreadsheet mode.
--bmx-data-grid-cell-padding Space either side of a cell's content.
--bmx-data-grid-detail-background Around a row's detail panel.
--bmx-data-grid-font-size The cells' text size.
--bmx-data-grid-footer-background The totals row.
--bmx-data-grid-group-background A group's heading row.
--bmx-data-grid-header-background Behind the headings.
--bmx-data-grid-header-height The headings' height.
--bmx-data-grid-header-text The headings' text.
--bmx-data-grid-height How tall the grid is, toolbar and status included.
--bmx-data-grid-line The lines between rows and columns.
--bmx-data-grid-pinned-background A row pinned to the top.
--bmx-data-grid-radius The corners of the grid.
--bmx-data-grid-range The chosen cells.
--bmx-data-grid-row-alternate Every other row, in the striped look.
--bmx-data-grid-row-background A row.
--bmx-data-grid-row-height Each row's height. Set it to override the density.
--bmx-data-grid-row-hover A row under the pointer.
--bmx-data-grid-row-selected A chosen row.
--bmx-data-grid-scrollbar-thumb The scrollbars' thumbs.
--bmx-data-grid-scrollbar-track The scrollbars' tracks.
--bmx-data-grid-tree-indent How far each level of a tree is indented.