Skip to content

Data Grids ​

The built-in grid enhances a server-rendered <table>. Tabulator is opt-in per element for grouped and tree data. No grid library is vendored by default.

The component-level contract — every markup hook, option, event and the accessibility checklist — is in Tables & Data Grids, which is the single writer for it. This page covers only the vendor decision and the Tabulator integration.


The built-in grid (default) ​

[data-av-datagrid] with no library attribute is handled by this product's own code. It needs no vendor at all, and it is the default on all fourteen grid-bearing pages.

The contract it is built around ​

The rows come from the server-rendered table. Nothing renders them client-side, so the page works with JavaScript disabled, the markup keeps real <table> semantics for assistive technology, and AdminVora.destroy(root) puts the original table back — asserted in tests/tabulator.mjs.

That decision is what rules out a rendering library, and it is worth stating plainly because the trade is real rather than obvious. A grid library takes an array and renders the DOM; several can read an existing table first, but they then replace it, and the fallback is gone after one navigation. For a template whose buyers render rows from Blade, Django templates or ERB, the markup is the data source.

What it does on top of that markup: sorting (reading data-av-value, never the rendered text, so €1,240.00 sorts as 1240), search, status filters, pagination, row selection with a three-state select-all, a bulk-action bar, empty and filtered-empty states, and CSV export.

Two behaviours are easy to get wrong and are done here deliberately:

  • CSV export neutralises formula injection. A cell beginning =, +, -, @, tab or carriage return is executed on open by Excel and Sheets; each is prefixed with an apostrophe. The file carries a UTF-8 BOM, or Excel on Windows reads non-ASCII as the system code page.
  • Pagination hands focus on. The pagination bar is rebuilt on every render, so pressing a page button with the keyboard would otherwise drop document.activeElement onto <body> — page two on screen, and the next Tab starting again from "Skip to main content". The equivalent control is refocused after the rebuild, falling back to the current page when Next lands on the last page and disables the button that was just pressed.

Row volume beyond a few thousand is handled by virtual scrolling rather than by a vendor; see Virtual scrolling.

Why no grid library is vendored ​

Grid.js, DataTables and their family are all capable and all MIT. None is here, and the reason is the contract above rather than an assessment of their quality:

Why it is not vendored
Grid.jsRenders from a data array. Its from: option reads an existing table and then replaces it, which removes the no-JS fallback and the native table semantics
DataTables 2Same rendering model, and it is the only candidate that would pull jQuery onto the page
Grid libraries generallyThe built-in grid is roughly a thousand lines of this product's own code, well under what a vendored grid adds to the bundle — so the swap would not save payload, it would add a dependency

If your application renders rows client-side from an API already, a rendering library is the right tool and this grid is the wrong one. The honest boundary is that AdminVora is built for server-rendered markup.


Tabulator (advanced) ​

MIT. The largest chunk in the bundle by a wide margin, which is why nothing loads it unless a page asks: data-av-datagrid-library="tabulator" is per element, not per page or per build.

Use it for the things the built-in grid deliberately does not do — row grouping, column calculations, frozen columns, tree data and inline editing.

The rows still come from a server-rendered <table>. Tabulator builds into a container of its own, so the source table is moved aside rather than destroyed: it is hidden while the grid is live and restored by destroy(), which is what keeps the no-JS fallback true on a second visit under a client-side router. A wrapper with no <table> inside it logs an error and is skipped.

html
<div data-av-datagrid
     data-av-datagrid-library="tabulator"
     data-av-datagrid-height="320px"
     data-av-datagrid-options='{
       "groupBy": "status",
       "columns": [
         { "field": "product", "title": "Product" },
         { "field": "sku", "title": "SKU" },
         { "field": "status", "title": "Status" },
         { "field": "stock", "title": "On hand", "hozAlign": "right", "bottomCalc": "sum" }
       ]
     }'>
  <table class="av-table">
    <caption class="av-visually-hidden">Stock by fulfilment status</caption>
    <!-- thead with data-av-field on each th, tbody rows with data-av-value on each cell -->
  </table>
</div>

data-av-datagrid-options is one JSON object, merged over data, layout: 'fitColumns' and the height. Invalid JSON logs an error and skips that grid rather than throwing. Every key is Tabulator's own — this product adds no option vocabulary of its own here.

Columns are read off the markup: data-av-field on each th names the column, and data-av-value on a cell is what gets read, for the same reason the built-in grid sorts on it — €1,240.00 orders between €1,199 and €13 as a string.

CapabilityBuilt-in gridTabulator
Sort, search, filter, paginate✓✓
Row selection and bulk actions✓✓
CSV export✓✓ (its own download())
Virtual scrolling✓✓
Row grouping✗✓
Tree / hierarchical data✗✓
Frozen columns✗✓
Column calculations (sum, avg)✗✓
Inline cell editing✗✓
Column resize + reorder✗✓
Loads a vendor✗✓

Getting the instance ​

The seam is the ready event, which hands over both the element and the live Tabulator instance — from there it is Tabulator's own API, including its exporters:

js
document.addEventListener('av:tabulator:ready', (e) => {
  const { el, instance } = e.detail;
  instance.download('csv', 'stock.csv');
});

Theming ​

Tabulator ships its own stylesheet, vendored into the plugins layer, and src/scss/plugins/_tabulator.scss re-points its greys at tokens:

scss
@layer plugins {
  .tabulator {
    background: transparent;
    border: 0;
    font-family: var(--av-font-sans);
    font-size: var(--av-font-size-sm);

    .tabulator-header {
      background: var(--av-surface-sunken);
      border-block-end: 1px solid var(--av-border-subtle);
      color: var(--av-text-muted);
      font-weight: var(--av-font-weight-semibold);
    }

    .tabulator-row {
      background: var(--av-surface-raised);
      border-block-end: 1px solid var(--av-border-subtle);
      &:hover { background: var(--av-table-row-hover-bg); }
    }

    .tabulator-cell { padding: var(--av-space-3) var(--av-space-4); border: 0; }
  }
}

Its grouped-grid ARIA is a known limitation — see Known Limitations.


DataTables (migrating away from it) ​

DataTables is not vendored, and tabulator is the only value data-av-datagrid-library accepts.

This section is kept because "I have a DataTables screen, what does it become here?" is a fair question. The answer is the built-in grid, and most of the mapping is markup rather than configuration:

DataTablesAdminVora equivalent
columns: [{ data, render }]The server-rendered <table>. Rendering is your template's job
dom: 'Bfrtip'Markup — the toolbar is yours
searching: truedata-av-grid-search on an input
paging: true, pageLength: ndata-av-grid-per-page on the grid
ordering: truedata-av-sort on a th, data-av-value on the cells
select extensiondata-av-grid-select-all and data-av-grid-row-check
buttons: ['csv']data-av-grid-export on a button
buttons: ['excel','pdf']No equivalent. CSV is the only format that ships
responsive extension.av-table--cards or .av-table--sticky-col — see Responsive
serverSide: true, ajax: urlNo equivalent: the built-in grid does not fetch
drawCallbackNo equivalent event today

The hooks above are documented in full, with their defaults, in Tables & Data Grids.


Performance ​

RowsStrategy
< 1,000The built-in grid, client-side
1,000–10,000Virtual scrolling, or Tabulator
MorePaginate on the server with ordinary links, and require a filter before showing results

The built-in grid's search filters rows already in the document, so it needs no debounce and issues no request.


Checklist ​

  • [ ] Server-rendered rows present as the no-JS fallback
  • [ ] data-av-value carries the sortable form on every cell whose rendering differs from its value
  • [ ] aria-sort maintained on the sorted column
  • [ ] Empty and filtered-empty states both written, and worded differently
  • [ ] Selection state announced, and select-all reports aria-checked="mixed" when partial
  • [ ] Exported CSV opened in Excel and Sheets, including a row beginning =
  • [ ] Keyboard: page through the grid and confirm focus survives each render
  • [ ] AdminVora.destroy(root) restores the source table if the page is client-routed

Read next: Calendar & Scheduling.

Documentation for @creativeigniter/adminvora