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

A data grid of 5,000 items with searchA data grid of 5,000 items with search

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

A cell being edited, with a validation messageA cell being edited, with a validation message

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

OptionDefaultWhat 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
height480Height of the scrolling area in pixels
rowHeight40Row height in pixels. Rows are one line; longer text is cut off with "…".
searchnoneA search input, or its selector, that filters as people type
query''A starting search
sortnone{ key, direction: 'asc' | 'desc' }
emptyText"Nothing to show"Shown when there are no rows. With a search, it says 'No results for "…"'.
onRowClicknone(row): makes rows clickable, and Enter on a focused row too
onCellEditnone({ row, key, value, previous }): save an edit

Columns

FieldDefaultWhat 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
widthshares the spacePixels, or any CSS width
alignright for numbers'left', 'center' or 'right'
sortabletrueClick the header to sort ascending, then descending
editablefalsetrue, or (row) => boolean
formatby type(value, row) => string for display. Sorting still uses the raw value.
validatenone(value, row) => message or null

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.