Export Plugin

The Export plugin lets users download grid data as CSV, JSON, or other formats with a single click or API call. Great for reporting, data backup, or letting users work with data in Excel.

Installation

import '@toolbox-web/grid/features/export';

Basic Usage

Enable the feature and call exportCsv() or exportJson() when you’re ready to download. You can also combine it with the selection feature to export only selected rows.

TypeScript

import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' }
  ],
  features: {
    export: {
      fileName: 'employees',
      includeHeaders: true,
    },
  },
};

// Trigger export via button click
document.getElementById('export-btn').addEventListener('click', () => {
  const plugin = grid.getPluginByName('export');
  plugin.exportCsv();
});

React

import '@toolbox-web/grid-react/features/export';
import { DataGrid, useGrid } from '@toolbox-web/grid-react';

function EmployeeGrid({ data }) {
  const { ref, element } = useGrid();

  const handleExport = () => {
    element?.getPluginByName('export')?.exportCsv();
  };

  return (
    <>
      <button onClick={handleExport}>Export CSV</button>
      <DataGrid
        ref={ref}
        rows={data}
        columns={[
          { field: 'name', header: 'Name' },
          { field: 'email', header: 'Email' },
          { field: 'department', header: 'Department' },
        ]}
        export={{ fileName: 'employees', includeHeaders: true }}
      />
    </>
  );
}

Vue

<script setup>
import '@toolbox-web/grid-vue/features/export';
import { TbwGrid, TbwGridColumn, useGrid } from '@toolbox-web/grid-vue';

const data = [
  { name: 'Alice', email: 'alice@example.com', department: 'Engineering' },
  { name: 'Bob', email: 'bob@example.com', department: 'Marketing' },
];

const { gridElement } = useGrid();

const handleExport = () => {
  gridElement.value?.getPluginByName('export')?.exportCsv();
};
</script>

<template>
  <div>
    <button @click="handleExport">Export CSV</button>
    <TbwGrid :rows="data" :export="{ fileName: 'employees', includeHeaders: true }">
      <TbwGridColumn field="name" header="Name" />
      <TbwGridColumn field="email" header="Email" />
      <TbwGridColumn field="department" header="Department" />
    </TbwGrid>
  </div>
</template>

Angular

// Feature import - enables the [exportFeature] input
import { GridExportDirective } from '@toolbox-web/grid-angular/features/export';
import { Component } from '@angular/core';
import { Grid, injectGrid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-data-grid',
  imports: [Grid, GridExportDirective],
  template: `
    <button (click)="handleExport()">Export CSV</button>
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [exportFeature]="{ fileName: 'employees', includeHeaders: true }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class DataGridComponent {
  grid = injectGrid();
  rows = [];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ];

  handleExport() {
    const plugin = this.grid.element()?.getPluginByName('export');
    plugin?.exportCsv();
  }
}

Demos

Default Export

EXPORT

Include headers Include column headers in export

Visible only Export only visible columns

Selected only Export only selected rows

Export CSV Export Excel Export JSON

Show source

Export all visible data to CSV. Toggle “Selected only” and select some rows to export just those.

Configuration Options

Option	Type	Default	Description
fileName	string	'export'	Base filename (without extension)
includeHeaders	boolean	true	Include column headers in export
onlyVisible	boolean	true	Export only visible columns
onlySelected	boolean	false	Export only selected rows (requires SelectionPlugin)

Programmatic API

The ExportPlugin provides methods for exporting data with fine-grained control over which columns and rows to include. Like the ClipboardPlugin, it accepts columns and rowIndices parameters so you can export exactly the data you need.

Basic Export

const exportPlugin = grid.getPluginByName('export');

// Export all visible data to CSV
exportPlugin.exportCsv();

// Export to Excel XML
exportPlugin.exportExcel();

// Export to JSON
exportPlugin.exportJson();

Export with Column/Row Control (ExportParams)

const exportPlugin = grid.getPluginByName('export');

// Export specific columns
exportPlugin.exportCsv({
  columns: ['name', 'email', 'department'],
  fileName: 'contacts',
  includeHeaders: true,
});

// Export specific rows
exportPlugin.exportCsv({
  rowIndices: [0, 3, 7],
  fileName: 'selected-employees',
});

// Export specific columns from specific rows
exportPlugin.exportExcel({
  columns: ['name', 'salary'],
  rowIndices: [0, 1, 2],
  fileName: 'salary-report',
});

ExportParams Reference

Option	Type	Default	Description
fileName	string	config value	File name (without extension)
columns	string[]	-	Specific column fields to export
rowIndices	number[]	-	Specific row indices to export
includeHeaders	boolean	config value	Include column headers in export
processCell	(value, field, row) => any	-	Custom cell value processor
processHeader	(header, field) => string	-	Custom header processor
mode	'raw' | 'formatted'	'raw'	'raw' = underlying typed values; 'formatted' = what the grid displays (column.format + type defaults applied)
fileExtension	string	'.xls'	Override file extension for Excel export (e.g. '.xml')
excelStyles	ExcelStyleConfig	-	Excel style configuration (Excel only)

Custom Output / .xlsx Hand-off

The plugin exposes data accessors so you can drive the export pipeline without producing a download — useful for piping rows into a real OOXML writer (e.g. ExcelJS), copying CSV to the clipboard, sending data to a server, or pre-processing before download.

Method	Returns	Purpose
export(params?)	Record<string, unknown>[]	Resolve the rows that would be exported, keyed by column.field
formatCsv(data, params?, options?)	string	Format already-resolved rows as CSV (no download)
formatExcel(data, params?)	string	Format already-resolved rows as Excel XML (no download)
getResolvedColumns(params?)	ColumnConfig[]	The columns (in order) an export would include

All accessors honour onlyVisible, onlySelected, columns, and rowIndices (which columns/rows are included), and processCell (per-cell transformation — applied once on the values that get written).

export() additionally honours mode because it owns value resolution. formatCsv() / formatExcel() are pure formatters: they write whatever you pass in (after running processCell) and do not apply mode — use export({ mode: 'formatted' }) upstream if you need displayed values.

import { queryGrid } from '@toolbox-web/grid';
import type { ExportPlugin } from '@toolbox-web/grid/plugins/export';

const grid = queryGrid('tbw-grid');
const exporter = grid.getPluginByName('export') as ExportPlugin;

// 1. "Export what I see" — column.format applied
exporter.exportCsv({ mode: 'formatted' });

// 2. Get the rows without producing a file
const rows = exporter.export();

// 3. Compose: copy CSV to the clipboard
const csv = exporter.formatCsv(exporter.export());
await navigator.clipboard.writeText(csv);

// 4. Hand off raw rows to a real .xlsx writer
import ExcelJS from 'exceljs';
const cols = exporter.getResolvedColumns();
const workbook = new ExcelJS.Workbook();
const sheet = workbook.addWorksheet('Sheet1');
sheet.columns = cols.map((c) => ({ header: c.header ?? c.field, key: c.field }));
sheet.addRows(exporter.export());
const buffer = await workbook.xlsx.writeBuffer();

mode: 'raw' | 'formatted'

• 'raw' (default) — values straight from the row (Date stays Date, numbers stay numbers). Identical to the pre-existing exportCsv / exportExcel / exportJson output, so opting into the new methods is non-breaking.
• 'formatted' — applies the column-type default formatter and column.format(value, row), returning the same string the user sees in the cell. processCell runs last on the formatted value.

Styled Excel Export

The export plugin produces XML Spreadsheet 2003 output — a single-XML format natively understood by Excel, without any external dependencies.

About the file extension

The correct extension for XML Spreadsheet 2003 is .xml, but most operating systems open .xml files in a web browser instead of Excel. For this reason the export defaults to .xls, which ensures the file opens directly in Excel.

The trade-off is that Excel shows a warning when opening the file:

“The file format and extension of ‘filename.xls’ don’t match. The file could be corrupted or unsafe. Unless you trust its source, don’t open it. Do you want to open it anyway?”

Clicking Yes opens the file normally — the data is not corrupt.

If your users are comfortable opening .xml files in Excel (e.g. via right-click → “Open with”), you can set fileExtension: '.xml' to avoid the warning entirely:

exportPlugin.exportExcel({ fileExtension: '.xml' });

Pass an excelStyles object in ExportParams to control header styles, per-column formatting, dynamic cell styling, column widths, and more.

Export Plain Excel Export Styled Excel

Show source

Click Export Styled Excel to download a formatted .xls file with bold headers, currency-formatted salaries, and color-coded status cells. Compare with Export Plain Excel to see the difference.

Header & Default Styles

exportPlugin.exportExcel({
  fileName: 'report',
  excelStyles: {
    headerStyle: {
      font: { bold: true, size: 12, color: '#FFFFFF' },
      fill: { color: '#4472C4' },
      alignment: { horizontal: 'Center' },
    },
    defaultStyle: {
      font: { name: 'Calibri', size: 10 },
    },
  },
});

Per-Column Styles (Financial Report)

exportPlugin.exportExcel({
  fileName: 'financial-report',
  excelStyles: {
    headerStyle: { font: { bold: true }, fill: { color: '#D9E2F3' } },
    columnStyles: {
      revenue: { numberFormat: '$#,##0.00', alignment: { horizontal: 'Right' } },
      margin: { numberFormat: '0.0%' },
      date: { numberFormat: 'yyyy-mm-dd' },
    },
    columnWidths: { name: 25, revenue: 15, margin: 10, date: 12 },
  },
});

Dynamic Cell Styling (Conditional Colors)

exportPlugin.exportExcel({
  fileName: 'status-report',
  excelStyles: {
    cellStyle: (value, field) => {
      if (field === 'status') {
        if (value === 'Active') return { fill: { color: '#C6EFCE' }, font: { color: '#006100' } };
        if (value === 'Inactive') return { fill: { color: '#FFC7CE' }, font: { color: '#9C0006' } };
      }
      return undefined; // fall through to column/default style
    },
  },
});

Auto-Fit Column Widths

exportPlugin.exportExcel({
  excelStyles: { autoFitColumns: true },
});

ExcelStyleConfig Reference

Option	Type	Default	Description
headerStyle	ExcelCellStyle	-	Style applied to all header cells
defaultStyle	ExcelCellStyle	-	Default style for all data cells
columnStyles	Record<string, ExcelCellStyle>	-	Per-column style overrides (keyed by field)
cellStyle	(value, field, row) => ExcelCellStyle | undefined	-	Callback for per-cell dynamic styling
columnWidths	Record<string, number>	-	Column widths in characters (keyed by field)
autoFitColumns	boolean	false	Auto-fit column widths from content

ExcelCellStyle Properties

Property	Type	Description
font	object	{ name?, size?, bold?, italic?, color? }
fill	object	{ color, pattern? } — pattern defaults to 'Solid'
numberFormat	string	Excel format code (e.g. '#,##0.00', '0%', 'yyyy-mm-dd')
alignment	object	{ horizontal?, vertical?, wrapText? }
borders	object	{ top?, bottom?, left?, right? } — each { style, color? }

Events

Export CSV Export JSON

Event Log: Clear

Event	Detail	Description
export-complete	{ format, fileName, rowCount, columnCount }	Fired after an export completes

Server-Side Considerations

The ExportPlugin exports the rows currently held in memory (grid.rows). It has no async or server-side support — it cannot fetch data it hasn’t already loaded.

Partial data with ServerSidePlugin

When combined with the ServerSidePlugin, only cached blocks are available for export. Rows the user hasn’t scrolled to yet are placeholder objects and will not be included. If you need to export the full server dataset, fetch all rows from your API and pass them to the export method directly:

const allRows = await fetch('/api/data?all=true').then(r => r.json());
grid.rows = allRows;
grid.getPluginByName('export').exportCsv();

See Also

• Clipboard — Copy cells to clipboard
• Print — Print the grid
• Server-Side Data — Block-based virtual scrolling for large datasets