<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
= 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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
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
| Event | Detail | Description |
|---|---|---|
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
| Method | Signature | Description |
|---|---|---|
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
| Slot | Description |
|---|---|
(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
| Part | Description |
|---|---|
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
| Property | Description |
|---|---|
--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. |