Data grid
On this page
phApp.dataGrid() shows thousands of rows smoothly by only drawing the rows on screen. It adds
search, sorting and inline editing with validation. For up to a few hundred rows, a
table is simpler and prints better.
Add ph-app-datagrid.js after ph-app.js on pages with a data grid:
<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app-datagrid.js"></script>
Usage


Figure 1: A data grid of 5,000 items, with a search field in the toolbar
<section class="ph-card ph-card--flush">
<header class="ph-card-header">
<div>
<h2 class="ph-card-title">Items</h2>
<p class="ph-card-description">5,000 items. Double-click Status, Stock or Restock to edit.</p>
</div>
</header>
<div class="ph-toolbar">
<label class="ph-search">
<span class="ph-visually-hidden">Search items</span>
<svg class="ph-icon" ...>...</svg>
<input class="ph-input" type="search" id="item-search" placeholder="Search items" />
</label>
</div>
<div id="items"></div>
</section>
const STATUSES = ['Active', 'Low stock', 'On order', 'Discontinued'];
const grid = phApp.dataGrid('#items', {
label: 'Items',
rows: items,
search: '#item-search',
height: 360,
columns: [
{ key: 'id', label: '#', type: 'number', width: 80 },
{ key: 'name', label: 'Item' },
{ key: 'warehouse', label: 'Warehouse' },
{
key: 'status',
label: 'Status',
editable: true,
validate: (value) => (STATUSES.includes(value) ? null : `Status must be one of ${STATUSES.join(', ')}`),
},
{ key: 'stock', label: 'Stock', type: 'number', editable: true, width: 110 },
{ key: 'restock', label: 'Restock', type: 'date', editable: true, width: 150 },
],
onCellEdit: ({ row, key, value }) =>
phApp.fetchJSON(`api/items/${row.id}`, { method: 'PATCH', body: { [key]: value } }),
onRowClick: (row) => openMemberDrawer(row.id),
});
Editing


Figure 2: Editing a cell in place
Editable cells open an input on double-click, or on Enter or F2 when focused. Enter saves, Escape
cancels, and Tab saves and moves to the next editable cell. If validate returns a message, it
shows under the cell and the value isn't saved.
The grid shows the new value straight away and calls onCellEdit. If that throws, rejects or
returns false, it puts the old value back and shows the toast "Couldn't save Status. The change was
undone."
Options
| Option | Default | What it does |
|---|---|---|
columns | (required) | The columns (see below) |
rows | (required) | The row objects |
label | (required) | The grid's accessible name |
rowKey | 'id' | The property, or a function, that identifies a row |
height | 480 | Height of the scrolling area in pixels |
rowHeight | 40 | Row height in pixels. Rows are one line; longer text is cut off with "…". |
search | none | A search input, or its selector, that filters as people type |
query | '' | A starting search |
sort | none | { key, direction: 'asc' | 'desc' } |
emptyText | "Nothing to show" | Shown when there are no rows. With a search, it says 'No results for "…"'. |
onRowClick | none | (row): makes rows clickable, and Enter on a focused row too |
onCellEdit | none | ({ row, key, value, previous }): save an edit |
Columns
| Field | Default | What it does |
|---|---|---|
key | (required) | The row property shown |
label | (required) | The header text |
type | 'text' | 'text', 'number' or 'date': sets sorting, alignment, display and the edit input |
width | shares the space | Pixels, or any CSS width |
align | right for numbers | 'left', 'center' or 'right' |
sortable | true | Click the header to sort ascending, then descending |
editable | false | true, or (row) => boolean |
format | by type | (value, row) => string for display. Sorting still uses the raw value. |
validate | none | (value, row) => message or null |
Search
Search matches rows that contain every word typed, in any column, ignoring case and accents. It waits 120 ms after typing stops.
Methods
phApp.dataGrid() returns setRows(rows), setQuery(query), setSort(sort), visibleRows() (as
searched and sorted, for exporting what's on screen), scrollToRow(key), refresh() and
destroy().
phApp.csv.download(phApp.csv.filename('items'), grid.visibleRows(), [
{ header: 'Item', value: (item) => item.name },
{ header: 'Status', value: (item) => item.status },
]);
React
import { DataGrid } from 'ph-app-kit-react/datagrid';
<DataGrid label="Items" rows={items} columns={columns} query={query} onCellEdit={save} height={480} />
React columns can also take render for custom cell content.
Guidelines
- Use it for more than a few hundred rows, or when people edit many values in a row.
- Say which columns are editable in the card description.
- Validate on the client for quick feedback, and on the server for safety.