# Data export and printing
**CSV / TSV / JSON export and copy-to-clipboard are free** in the community
**[@svgrid/grid](https://www.npmjs.com/package/@svgrid/grid)** - the commodity
"data out" every grid needs. The richer formats - **Excel (xlsx)**, **legacy
Excel (xls)**, **PDF**, styled **HTML**, **XML**, **Markdown**, multi-sheet
workbooks, password protection, conditional-format export, and the drop-in
export menu - ship in the paid
**[@svgrid/enterprise](https://www.npmjs.com/package/@svgrid/enterprise)** add-on,
which reuses the exact same serializers so the two tiers feel like one product.
For the report built step by step, with a live grid under most steps, see [Export: a report to Excel and PDF](https://svgrid.com/docs/help/export/report/); this page is the reference.
| Capability | Package |
| ---------- | ------- |
| CSV / TSV / JSON export, copy-to-clipboard (TSV / CSV / Markdown) | **Free** (`@svgrid/grid`) |
| Excel `.xlsx` (typed cells, styles, conditional formatting, tables, multi-sheet) | Enterprise |
| PDF, styled HTML, XML, legacy `.xls`, password-protected export | Enterprise |
| `exportValue` hook, conditional-format export, `SvExportMenu`, `print()` | Enterprise |
## Free: CSV / TSV / JSON + clipboard
The community grid's `SvGridApi` carries four zero-dependency methods - no
license, no peer deps:
The examples on this page run against these rows:
```svelte
```
```ts
await api.exportCsv({ filename: 'orders' }) // orders.csv (BOM + Excel-friendly)
await api.exportTsv() // grid.tsv
await api.exportJson({ rows: 'selected' }) // grid.json, checked rows only
await api.copyToClipboard({ format: 'tsv' }) // paste straight into Excel / Sheets
```
Every method:
- defaults to the **current view** (`rows: 'selected' | 'all'` to change),
- formats values **as shown on screen** (currency, dates) - pass
`rawValues: true` for the underlying values,
- accepts a `columns: string[]` field subset (in that order),
- runs on a chunked, cancelable loop (`signal`, `onProgress`) so a 100k-row
export never freezes the tab,
- returns the serialized text; pass `download: false` to skip the download
and just get the string.
```svelte
(api = a)} />
```
The rest of this page covers the **Enterprise** formats.
Try the export bar below - downloads run in your browser; the bundled
license key removes the unlicensed watermark:
> Live demo: Export + Print - https://svgrid.com/demos/21-export-and-print/
## What it is
`@svgrid/enterprise` augments the `SvGridApi` you already get from
`` with two methods:
- `api.exportData({ format, filename?, columns?, rows?, pageOrientation? })`
- `api.print({ title?, columns?, rows?, orientation? })`
Both methods default to **the currently displayed rows** - sort, filter,
or paginate the grid, and the export reflects that view automatically.
## When to use it
- Reporting flows where users want to take the grid offline (spreadsheets,
emailed PDFs).
- Compliance / audit trails that require a printable artifact.
- Quick CSV/TSV pulls for downstream pipelines.
If you only need machine-readable data, prefer CSV / TSV - they have no
peer dependencies and produce the smallest files. Use xlsx / PDF only
when the recipient expects formatted documents.
## Minimal example
```svelte
```
## Install
```bash
pnpm add @svgrid/enterprise
# Optional - install only the peers you actually use:
pnpm add jszip # required for xlsx
pnpm add pdfmake # required for pdf
```
CSV, TSV, HTML, and Print have **no extra dependencies**. The peer
dependencies are lazy-loaded only when you call the format that needs
them.
## Licensing
`@svgrid/enterprise` has a tiered license gate:
| Key state | Behavior |
| ------------------------------------------ | -------- |
| No key set (`setLicenseKey()` not called) | Feature works. Grid shows an unlicensed watermark linking to svgrid.com/pricing; console.log emits a one-time nudge. |
| A key that is not your license key | Same as no key: the feature works, with the watermark and a one-time console warning. |
| Your license key | Works silently. |
Buy a production key at ($599 / developer /
year). To evaluate, you need no key at all: everything runs with a watermark.
## Reference
### `setLicenseKey(key: string): void`
Stores the key in module state. Call once at app startup (e.g. in
`main.ts`). Subsequent calls overwrite.
### `clearLicenseKey(): void` · `hasValidLicense(): boolean` · `dismissUnlicensedNudge(): void`
Programmatic helpers. `hasValidLicense()` is useful when you want UI to
branch on license status. `dismissUnlicensedNudge()` removes the
watermark and stops the MutationObserver - call it after setting a
valid key if you loaded the module without one during testing.
### `installEnterprise(api): EnterpriseGridApi`
Mutates the given `SvGridApi` to add `exportData` and `print`. Returns
the same object with the augmented type, so existing references keep
working.
### `api.exportData(opts)` - `Promise`
| Option | Type | Default | Notes |
| ----------------- | ----------------------------------------------------- | -------------------- | ----- |
| `format` | `'xlsx' \| 'xls' \| 'pdf' \| 'csv' \| 'tsv' \| 'html' \| 'json' \| 'xml' \| 'md'` | required | `xlsx` needs `jszip`, `pdf` needs `pdfmake`. `xls` / CSV / TSV / HTML / JSON / XML / Markdown are dependency-free. |
| `pdf` | `PdfExportOptions` | - | PDF layout: page size, margins, title / subtitle / logo, theme colors, column widths, repeated header, page numbers. See "PDF options". |
| `conditionalFormats` | `ConditionalFormat[]` | - | Same array as ``; carried into pdf / xlsx / html. See "Conditional formatting in exports". |
| `freezeHeader` | `boolean` | `true` | Freeze the header row (xlsx / xls). |
| `freezeColumns` | `number` | pinned cols | Freeze this many leading columns (xlsx / xls). Defaults to the grid's left-pinned columns. |
| `autoFitColumns` | `boolean` | `true` | Size columns to content (xlsx / xls); a column's explicit `width` wins. |
| `precisionSafe` | `boolean` | `false` | Export long integer IDs (> 15 digits) as text so Excel's float precision doesn't round them (xlsx / xls). |
| `excelTable` | `boolean \| { totalsRow?; style? }` | - | Wrap single-sheet xlsx in a native Excel Table (filter dropdowns, banded rows; `{ totalsRow: true }` adds SUM formulas). |
| `download` | `boolean` | `true` | When false, return the {@link ExportResult} without downloading. |
| `filename` | `string` | `"grid"` | Extension is appended if missing. |
| `columns` | `{ field; header?; format?; align?; exportValue? }[]` | grid's own columns | Drives column selection + header labels. Auto-derived from the grid (with each column's `format`) when omitted. See `exportValue` below. |
| `rows` | `ReadonlyArray \| 'displayed' \| 'selected' \| 'all'` | `'displayed'` | `'displayed'` = current filtered/sorted/paged view, `'selected'` = checked rows, `'all'` = full dataset, or pass an explicit array. |
| `rawValues` | `boolean` | `false` | By default the exporter writes the **formatted display value** (what you see). Set `true` to write raw underlying values (numbers stay numeric in xlsx). |
| `autoGroup` | `boolean` | `true` | Carry the grid's active row grouping into xlsx outline rows. Pass your own `groupBy` to override, or `false` to ignore. |
| `csv` | `{ delimiter?; eol?; bom? }` | `{ ',', '\r\n', BOM }` | CSV / TSV tuning. UTF-8 BOM is on by default so Excel opens it without mojibake. |
| `onProgress` | `(p) => void` | - | Progress for large exports: `{ phase, ratio, row?, total? }`, `phase` = `'project' \| 'serialize' \| 'write'`. |
| `signal` | `AbortSignal` | - | Cancel an in-flight export (checked between chunks). Rejects with `AbortError`. |
| `pageOrientation` | `'portrait' \| 'landscape'` | `"portrait"` | PDF only. |
| `merges` | `{ row; col; rowSpan?; colSpan? }[]` | `[]` | Merged cells (xlsx / pdf). Zero-based **body** row/col (header excluded). Single-sheet only; mutually exclusive with `groupBy` / `hierarchical`. |
### Faithful values (what you see is what you export)
By default the export renders each cell the way the grid does on screen: a
column with `format: { type: 'currency', currency: 'USD' }` exports `$19.95`,
a date column exports its formatted date, a percent column exports `42%`. This
holds for **every** format (csv / tsv / html / pdf / xlsx). Pass
`rawValues: true` to write the underlying values instead (e.g. feeding a data
pipeline that wants the numeric `19.95`).
For columns whose on-screen value comes from a **custom cell renderer**, a
`fieldFn`, or a lookup, give the column an `exportValue` hook - it takes
precedence over `format` and the raw field:
```ts
await api.exportData({
format: 'xlsx',
columns: [
{ field: 'company', header: 'Company' },
// a column rendered with a custom snippet on screen:
{ field: 'status', header: 'Status', exportValue: (row) => STATUS_LABELS[row.status] },
],
})
```
### Export only what's selected
```ts
// current view (default)
await api.exportData({ format: 'xlsx' })
// only the checked rows
await api.exportData({ format: 'xlsx', rows: 'selected' })
// the entire underlying dataset, ignoring filters/paging
await api.exportData({ format: 'csv', rows: 'all' })
```
### Large exports: progress + cancel
CSV / TSV / HTML are serialized natively (no peer dependency) and stream in
chunks, yielding to the event loop so a big export doesn't freeze the tab:
```ts
const controller = new AbortController()
await api.exportData({
format: 'csv',
rows: 'all',
signal: controller.signal,
onProgress: ({ ratio }) => updateProgressBar(ratio),
})
// controller.abort() rejects the export with an AbortError
```
### Excel-native numbers (xlsx)
A single-sheet `xlsx` export writes numeric, currency, percent, and date
columns as **real typed cells** with an Excel number format - so Excel can sum
and sort them, and they still display formatted (currency symbol, thousands,
`%`, date pattern) - via SvGrid's own OOXML writer. Set `rawValues: true` for
unformatted raw values. The grouped-outline, multi-sheet, image, and merged-cell
paths use the bundled writer (formatted-string cells). The legacy `xls` format
is always typed.
### Excel fidelity: freeze, auto-fit, hyperlinks
`xlsx` and `xls` exports polish the spreadsheet automatically:
- **Freeze header** - the header row stays visible when scrolling. On by
default; `freezeHeader: false` to disable, `freezeColumns: n` to also freeze
leading columns.
- **Auto-fit column widths** - columns are sized to their content. On by
default (`autoFitColumns: false` to disable); a column's explicit `width`
(pixels) always wins.
- **Hyperlinks** - give a column a `link(row)` hook to render clickable links.
Works in `xlsx`, `xls`, `html`, `pdf`, and `print`.
Single-sheet `xlsx` is written by SvGrid's own OOXML writer, so numbers/dates
stay typed with number formats, conditional-format colors are **real per-cell
fills**, and freeze/widths/hyperlinks all apply. (Grouped/outline, multi-sheet,
embedded-image, and merged-cell exports use the bundled writer.)
```ts
await api.exportData({
format: 'xlsx',
freezeHeader: true, // default
columns: [
{ field: 'name', header: 'Company', width: 220,
link: (row) => `https://crm.example.com/accounts/${row.id}` },
{ field: 'revenue', header: 'Revenue', format: { type: 'currency', currency: 'USD' } },
],
})
```
Conditional-format colors (data bars / color scales) already render as real
cell fills in `xlsx`, which is higher fidelity than the writer's built-in
rule-only conditional formatting - so we keep the per-cell approach.
### Get the file instead of downloading (`download: false`)
`exportData` returns an **`ExportResult`** for the dependency-free paths
(csv/tsv/html/json/xml/md, xls, pdf, single-sheet xlsx) so you can preview,
upload, email, or attach the file. With `download: false` it builds and returns
the file **without** triggering a browser download:
```ts
const res = await api.exportData({ format: 'xlsx', download: false })
// res: { blob, filename, mime, rowCount, byteSize }
await uploadToStorage(res.blob, res.filename)
```
The grouped / multi-sheet / image / blanket-styled xlsx paths use the vendored
writer, which downloads directly and returns `undefined` (and throws on
`download: false`).
### Excel Table (filter dropdowns + totals row)
Wrap a single-sheet xlsx in a native **Excel Table** - the user gets column
filter dropdowns, banded rows, structured references, and (optionally) a totals
row with live `SUM()` formulas:
```ts
await api.exportData({ format: 'xlsx', excelTable: { totalsRow: true } })
// or just `excelTable: true` for the table without a totals row
```
Column widths auto-fit and leading **pinned columns are frozen automatically**
(override with `freezeColumns`). For long IDs, `precisionSafe: true` writes them
as text so Excel's 15-digit float limit doesn't silently round `1002000300040005`.
### JSON / XML / Markdown
```ts
await api.exportData({ format: 'json' }) // array of { field: value } - defaults to raw values
await api.exportData({ format: 'xml' }) // value…
await api.exportData({ format: 'md' }) // GitHub-flavored Markdown table (great for docs / LLMs)
```
JSON defaults to **raw** values (real numbers/dates) since it's a data format;
pass `rawValues: false` for formatted strings. XML and Markdown use the
formatted display values.
### Copy to clipboard
`api.copyExport(opts)` serializes to the clipboard instead of downloading a
file - handy for "copy these rows into a spreadsheet or an email":
```ts
await api.copyExport({ format: 'tsv' }) // pastes into Excel / Sheets as columns (default)
await api.copyExport({ format: 'md', rows: 'selected' }) // Markdown table of the checked rows
await api.copyExport({ format: 'html' }) // rich text/html - keeps the table when pasted
```
Supported formats: `csv`, `tsv`, `html`, `json`, `xml`, `md`. `html` writes
both `text/html` (rich paste) and a `text/plain` fallback. Needs a secure
context and a user gesture (call it from a click).
### Conditional formatting in exports
Pass the same `conditionalFormats` array you give `` to carry the grid's
color scales, data bars, icon sets, and predicate rules into the **styled**
formats - PDF, xlsx, and HTML (and `print()`):
```ts
const conditionalFormats = [
{ type: 'colorScale', columns: ['score'], min: '#dcfce7', max: '#fee2e2' },
{ type: 'rule', columns: ['status'], when: ({ value }) => value === 'Overdue', background: '#fecaca' },
]
await api.exportData({ format: 'pdf', conditionalFormats })
await api.exportData({ format: 'xlsx', conditionalFormats }) // real cell fills in Excel
await api.print({ conditionalFormats })
```
Cell background, text color, and bold carry through as **real cell fills** in
`xlsx` (single-sheet), `xls`, `html`, and `pdf`; icon sets prepend their glyph
to the cell text.
In **xlsx**, **data bars** and **color scales** become **native Excel
conditional formatting** (`` rules) - Excel draws and
recomputes them itself, so they're interactive, not a static snapshot.
Predicate `rule` formats stay as computed per-cell fills. In the other styled
formats (`xls` / `html` / `pdf`) a data bar degrades to a light fill of the bar
color (cells can't hold a partial-width bar). The data formats (csv / tsv /
json / xml / md) are unstyled, so conditional formatting is ignored there.
Grouped PDF exports skip conditional formatting (the group/subtotal rows own the
layout).
### PDF options
The PDF is built from a full pdfmake document you control via `pdf`:
```ts
await api.exportData({
format: 'pdf',
filename: 'orders',
pdf: {
pageSize: 'A4', // 'A4' | 'A3' | 'A5' | 'LETTER' | 'LEGAL'
pageOrientation: 'landscape',
title: 'Q3 Orders',
subtitle: 'Generated by Ops',
logo: logoDataUrl, // top-left image (data URL)
headerColor: '#334155', // header row fill
zebra: true, // striped rows
columnWidths: '*', // '*' fill, 'auto', or a per-column pt array
// repeatHeader (default true), showPageNumbers (default true) also available
},
})
```
The header row repeats on every page, each page gets a `Page X of Y` +
date footer, per-column alignment is honored, and wide grids auto-switch to
landscape (override with `pdf.pageOrientation`).
The PDF looks like the grid it came from. With `pdf.matchTheme` (default
true) the exporter reads the mounted grid's computed colours - header fill
and text, body text, the zebra stripe, the lines, a group row's fill - so a
grid on the Ember theme or a Theme Builder palette prints in those colours
rather than the slate defaults. A dark theme lends only its header: the
page is white, so its body text and stripes would not read. The order of
precedence is explicit `pdf` colours (`headerColor`, `headerTextColor`,
`textColor`, `zebraColor`, `borderColor`, `groupColor`, ...), then
`styles`, then the theme, then the defaults. `styles.headerRow` /
`styles.rows` / `styles.rowAlternate` / `styles.cells` (A1 references, row
1 being the header) apply to the PDF table the way they do to xlsx and
html, `header` / `footer` lines print above and below the table, and
`merges` span data cells.
When the grid is grouped, the PDF carries the grouping: a bold **group header**
per cluster (nested for multi-level grouping) and a **subtotal row** summing the
number / currency columns - matching the xlsx outline export. It's on by
default (`autoGroup`); pass `groupBy` to override or `autoGroup: false` to get a
flat table.
#### Charts and a KPI strip
A report is rarely just the table. `pdf.charts` prints charts with it: hand
over the rendered chart's element (the `SvChart` wrapper or its `