ExportButton

Code

import { ExportButton, type ExportColumn } from "@fadymondy/nasaq/web";type Row = { id: string; name: string; email: string };const columns: ExportColumn<Row>[] = [  { id: "name", label: "Name" },  { id: "email", label: "Email" },];export function Toolbar({ all, filtered, selected }: { all: Row[]; filtered: Row[]; selected: Row[] }) {  return <ExportButton columns={columns} scopes={{ selected, filtered, all }} filename="contacts" />;}

Files · beta

Live examples and controls: ExportButton in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/export-action.json

The "Export" action of a list or a report. It opens a dialog where the user picks a format, which rows (the selection, the current filter or everything) and which columns, then builds the file in the browser with a progress state and a cancel button. The serializers are pure functions you can also use without the UI.

When to useCopy Anchor Link

• Letting people take table data out as CSV, Excel or JSON.
• Exporting rows that live on the server: give a scope a load function.
• Adding PDF by handing the component your own PDF builder.

When not to useCopy Anchor Link

• Downloading one known file: use a plain link or a Button.
• Sharing a link or inviting people: use ShareButton.
• Printing a page: call window.print() from a PageActions button.

ImportCopy Anchor Link

import { ExportButton, toCsv, toXlsx } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { ExportButton, type ExportColumn } from "@fadymondy/nasaq/web";

type Row = { id: string; name: string; email: string };

const columns: ExportColumn<Row>[] = [
  { id: "name", label: "Name" },
  { id: "email", label: "Email" },
];

export function Toolbar({ all, filtered, selected }: { all: Row[]; filtered: Row[]; selected: Row[] }) {
  return <ExportButton columns={columns} scopes={{ selected, filtered, all }} filename="contacts" />;
}

AnatomyCopy Anchor Link

ExportButton                  data-slot="export-button"    (or a menu when mode="menu")
└─ ExportDialog               data-slot="export-dialog"
   ├─ format cards            CSV, Excel, JSON (+ PDF with onExportPdf)
   ├─ rows scope              radios with row counts
   ├─ columns                 checkboxes with select all
   ├─ progress                data-slot="export-progress"  Progress + Cancel
   └─ result                  data-slot="export-done"      Download again / Done

APICopy Anchor Link

ExportButton (ExportActionProps<T>)

ExportDialog takes the same props plus open and onOpenChange, for opening it from your own control.

Serializers (pure, no DOM): toCsv(rows, { delimiter, newline, bom, guardFormulas }), csvField, toJson(records), toXlsx(rows, { sheetName, rtl }), zipStore, crc32, buildExportFile({ format, columns, rows, onProgress, signal }).

ExamplesCopy Anchor Link

Server rows behind a scope

<ExportButton
  columns={columns}
  scopes={{ all: { count: 12840, load: () => api.listAllContacts() } }}
  filename="all-contacts"
/>

PDF through a callback

<ExportButton
  columns={columns}
  scopes={{ all: rows }}
  onExportPdf={async (request, { signal, onProgress }) => {
    const res = await fetch("/api/pdf", { method: "POST", body: JSON.stringify(request.rows), signal });
    onProgress(1);
    return res.blob();
  }}
/>

CSV outside the UI

import { toCsv } from "@fadymondy/nasaq/web";

const csv = toCsv([["Name", "Note"], ["Sara", "=1+1"]], { bom: true }); // "=1+1" is exported as text

AccessibilityCopy Anchor Link

• The dialog traps focus and closes with Escape (not while a file is being built; use Cancel).
• Formats and rows are radio groups with their own legends; columns are checkboxes with a select-all that shows the mixed state.
• The progress bar has an accessible name; the result line is a role="status" live region.
• Formula-like text (=, +, -, @) is prefixed so a spreadsheet does not run it.

RTL & i18nCopy Anchor Link

• Strings ship in English and Arabic. CSV gets a UTF-8 BOM so Excel reads Arabic; XLSX sheets are right-to-left in Arabic.
• File names and counts stay left-to-right inside <bdi dir="ltr">; numbers follow the locale.

Styling & tokensCopy Anchor Link

• Built from Button, Dialog, RadioGroup, Checkbox, Progress and Alert; use their tokens. Extend with className.

Do / Don'tCopy Anchor Link

• Do give value for columns whose cell is not a plain field (dates, joined tags).
• Do use load for large or remote scopes so the rows are fetched only when chosen.
• Don't pass rendered React nodes as cell values; return text or numbers.
• Don't rely on PDF without onExportPdf.

RelatedCopy Anchor Link

• DataTable
• EntityList
• ShareButton

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-files-export-button--docs