api reference

Export, state and saved views

grid.export to Excel and CSV, grid.state, grid.views, pagination and scroll.

API reference › Export, state and saved views

grid.export

Method	Returns	Description
csv(opts)	string \| Blob	Fields sanitised against formula injection.
excel(opts)	Promise<Blob>	Real `.xlsx`, written without a ZIP dependency. Large exports stream.
clipboard(opts)	Promise	TSV, with the grid's own paste parser as its counterpart.
print(opts)	void	Switches virtualisation and pinning off for the printed document.
rows(mode)	Row[]	`'all'`, `'visible'` or `'selected'`.

Excel value conversion. A data type may declare toExcelValue and excelKind, because a spreadsheet's number formats are not free-form. A time of day is written as a fraction of a day under hh:mm:ss; a duration as days under [h]:mm:ss, where the brackets are what stop Excel wrapping at 24 hours. Both stay numeric, so they still sort and subtract in the sheet.

IP columns are stored as packed integers so they sort as addresses, and declare excelKind: 'string' so the dotted form is what reaches the file. Radix columns export decimal: OOXML cannot express base 16, and staying numeric was judged worth more than display fidelity.

grid.state

Method	Returns	Description
get()	GridState	Versioned and serialisable: `columns`, `columnOrder`, `filters`, `quick`, `sort`, `group`, `pivot`, `expanded`, `selection`, `scroll`, `pagination`.
apply(state, opts?)	object	Restore a view. Returns a report of anything it could not apply (a column that no longer exists, for instance) rather than failing silently.
baseline()	GridState \| null	The state the grid started in, captured once after `config.state` and any default view, so the baseline is the grid you shipped, not the one before your own configuration ran.
reset()	object \| null	Put the grid back to that baseline, as one undo entry. Clears anything the baseline does not mention, including the quick filter.
modified()	boolean	Whether anything has changed since construction. Lets a "restore" control disable itself rather than offering an action that would do nothing.

grid.views

Named states the user can return to. Views supplied in config.views.saved are defined views: listed apart in the picker, and neither renamable nor deletable, refused by the model as well as hidden in the interface. Views the user saves are their own and carry rename, share, default and delete.

createGrid(el, {
  views: {
    saved: [{ id: 'escalations', name: 'Escalations', description: 'Worst SLA first',
              state: { filters: { col: 'statusId', op: 'eq', value: 4 },
                       sort: [{ col: 'utilisation', dir: 'desc' }] } }],
    allowSave: true,   // false removes the save form entirely
    local: true,       // saved views live in this browser's localStorage, no backend
    // storage: { read, write }, // or bring your own backend; see the note below
  },
});

Method	Returns	Description
list() / get(id)	object[] / object
save(name, opts?)	object	Captures the current state. `opts`: `id`, `description`, `shared`, `isDefault`.
apply(id)	object \| null	One undo entry. Resets to the baseline first, so a view is a destination rather than a patch, the same view gives the same grid whatever was applied before it.
rename(id, name)	object \| null	Null for a defined view.
remove(id)	boolean	False for a defined view.
setDefault(id)	object \| null	`null` clears it. A default view is applied on load, without recording an undo entry.
export(id) / import(json)	object	A JSON payload. What "sharing" means is yours to decide.
diff(id)	object \| null	What applying a view would change.
reload()	void	Re-read from storage, discarding what is in memory.
activeId	string \| null

The grid makes no network calls. storage.write is a synchronous mirror. To persist to a server, listen for view:saved, view:renamed, view:removed and view:default: each carries the one view that moved, so you can send a single record rather than diffing two lists. Because the grid does not track whether your write landed, a failed request leaves the view visible locally: catch it and call views.reload().

views.local is the no-backend option: true stores views under a default localStorage key, shared by every grid on the origin; { key: '…' } picks a key of your own, for more than one grid whose views should stay apart. Given alongside an explicit storage, storage wins and local is ignored, with a console warning, the two are never merged. Built on createLocalViewStorage, exported for direct use (a custom key, or a different Storage-shaped backing such as sessionStorage) without the local shorthand.

grid.pagination

A window over the rows the query already produced, not another query. A page change re-slices; it does not re-filter, re-sort or re-group, so paging a million rows costs nothing beyond the repaint.

Method	Returns	Description
get()	{ page, pageSize, total, pageCount }	`total` is the filtered row count, so it moves when a filter does.
set({ page?, pageSize? })	void	Move, resize, or both. `pageSize: 0` turns paging off and shows everything. Emits `page:changed` once the rows have moved.

grid.scroll

Method	Returns	Description
position()	{ top, left }
toRow(row, align?)	void	`align`: `'start'`, `'centre'`, `'end'`.
toColumn(id)	void
to(at)	void	Scroll to `{ top, left }`. `left` is the logical offset: zero at the content's start whichever way the grid reads.
toCell(row, colId, align?)	void	Scroll a cell into view, both axes in one call. `row` is a row key or a display index.