Export and saved views: JavaScript Data Grid API

API reference › Export and saved views

grid.export

grid.import

The mirror of grid.export: rows coming in from delimited text - a CSV or TSV file, or the tab-separated block a spreadsheet puts on the clipboard. The pipeline is parse, infer each column's type, map the columns onto the grid's own fields, then preview and confirm. The API is always present; set config.import to add the DOM affordances (a "Import rows from CSV…" cell-menu item, a file drop target, and paste).

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  columns: [{ field: 'id' }, { field: 'age', type: 'integer' }],
  rows: [{ id: 'seed', age: 1 }],
  rowKey: 'id',
  // Opt in to the DOM affordances; the grid.import API is present either way.
  import: true,
});

// Preview changes nothing - it is what a confirm dialog shows.
const preview = grid.import.preview('id,age\nx,20\ny,30');

// Confirming appends the previewed rows; `age` arrives coerced to a number.
grid.import.apply(preview);

return `${preview.rowCount} previewed, ${grid.rows.count()} rows`;   // 2 previewed, 3 rows

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  columns: [{ field: 'id' }, { field: 'age', type: 'integer' }],
  rows: [{ id: 'x', age: 20 }, { id: 'y', age: 30 }],
  rowKey: 'id',
});

// Write a two-sheet workbook so there are real .xlsx bytes to read back.
const out = await grid.export.excel({
  sheets: [{ name: 'Summary' }, { name: 'Data' }],
});
const bytes = new Uint8Array(await out.arrayBuffer());

// List the workbook's sheets, in order, hidden sheets flagged.
const sheets = await grid.import.xlsxSheets(bytes);

// Read one of them by name - a zero-based index ({ sheet: 1 }) works too.
const preview = await grid.import.previewXlsx(bytes, { sheet: 'Data' });

return `${sheets.map((s) => s.name).join(', ')} / ${preview.rowCount} rows`;

grid.state

Scroll is opt-in, on both sides. It is transient UI state, not view state, so a saved view, the baseline and serialiseState's diff never carry it: get() omits it unless called with { scroll: true }, and apply() restores a scroll key only when it is present and apply is also called with { scroll: true } - so an old persisted state that still has one does not reopen the grid scrolled away from the top.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ id: 'n', field: 'n' }],
  rows: [{ id: '1', n: 'a' }],
});

const hasScrollByDefault = 'scroll' in grid.state.get();
const hasScrollOptedIn = 'scroll' in grid.state.get({ scroll: true });

const ignored = grid.state.apply({ version: 2, scroll: { top: 220, left: 0 } });
const scrollIgnored = !ignored.applied.includes('scroll');

const applied = grid.state.apply({ version: 2, scroll: { top: 220, left: 0 } }, { scroll: true });
const scrollApplied = applied.applied.includes('scroll');

const result = [hasScrollByDefault, hasScrollOptedIn, scrollIgnored, scrollApplied].join(',');
grid.destroy();
return result;

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
  },
});

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.

Paging over a paged or remote source

A paged or remote source holds only the rows it has fetched, so there is nothing to slice. Instead, page p is the row window [p × pageSize, (p + 1) × pageSize) of the server's answer to the current query, and moving to a page fetches the blocks that window needs - one request when the page size equals the source's own pageSize. The viewport scrolls within the page, rows still in flight draw as loading rows, and rows.get(0) is the first row of the page, exactly as on a memory grid. rows.count() is the page on screen; rows.matchCount(), rows.totalCount() and pagination.get().total are the whole result.

• Configure both. pagination: { enabled: true, pageSize: 250 } turns the pager on; source: { mode: 'paged', pageSize: 250, fetch } sets the block the server is asked for. Matching them makes every page one request. A headless grid honours the configured page size too, with no pager to apply it.
• A new query starts at page 0. A sort, a filter or a quick filter changes the list the server answers, so the page goes back to the first one and page:changed says so.
• No total yet is not the end. While total is null, the pager keeps "next" enabled and pageCount counts the pages known so far plus the next one.
• A source with no page model refuses by name. A stream or custom source that cannot window warns once (pagination:source-unsupported), shows no pager and keeps scrolling.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const asked = [];
const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'name' }],
  pagination: { enabled: true, pageSize: 250 },
  source: {
    mode: 'paged', pageSize: 250,
    fetch: async ({ range }) => {
      asked.push(`${range.start}-${range.end}`);
      const rows = [];
      for (let i = range.start; i < Math.min(range.end, 1000); i++) rows.push({ id: i, name: `row ${i}` });
      return { rows, total: 1000 };
    },
  },
});

const heard = [];
grid.on('page:changed', (e) => heard.push(e.page + 1));
const landed = new Promise((resolve) => grid.once('rows:changed', resolve));
grid.pagination.set({ page: 2 }); // the third page: rows 500 to 749
await landed;

const { page, pageCount, total } = grid.pagination.get();
const first = grid.rows.get(0).data.id;
grid.destroy();
return `page ${page + 1} of ${pageCount}, rows from ${first}, ${total} total, fetched ${asked.join(' ')}, page:changed to ${heard}`;

grid.scroll