import { downloadCsv } from '@uhg-abyss/web/tools/downloadCsv';

Overview

The downloadCsv utility provides a simple, agnostic way to generate and download CSV files. It handles CSV formatting, injection protection, filename sanitization, and works anywhere in your application—whether with DataTable, custom data, or external sources.

downloadCsv({
  columns: [
    { id: 'name', header: 'Name' },
    { id: 'email', header: 'Email' },
  ],
  data: [
    { name: 'Alice', email: 'alice@example.com' },
    { name: 'Bob', email: 'bob@example.com' },
  ],
  filename: 'contacts',
});

Features

• CSV injection protection: Automatically prefixes formula starters (=, +, -, @) with ' to prevent code injection
• Quote escaping: Handles values containing quotes and field separators correctly
• Filename sanitization: Removes invalid characters and normalizes filenames automatically
• Field separator flexibility: Supports custom separators for TSV, PSV, or other formats
• No runtime errors: Relies on TypeScript for type safety; minimal runtime validation

Common use cases

• Export filtered DataTable rows to CSV based on current filters or selection
• Generate reports from custom data structures
• Bulk data downloads with column selection
• Selective exports (e.g., only certain columns, only selected rows)

Parameters

Property	Type	Required	Default	Description
columns	TColumn[]	Yes	—	Column definitions specifying which fields to export and headers
data	TRow[]	Yes	—	Array of objects to export (one object = one row)
filename	string	No	'data'	Filename without extension; .csv is added automatically
fieldSeparator	string	No	','	Character(s) separating fields (e.g., ; for TSV)
columnAccessorKey	keyof TColumn	No	'id'	Column key used to read values from each row
columnLabelKey	keyof TColumn	No	'header'	Column key used for the CSV header label

Usage

Basic example

This example below creates and downloads a file named export.csv with two rows of data.

() => {
  const columns = [
    { id: 'age', header: 'Age' },
    { id: 'city', header: 'City' },
  ];

  const rows = [
    { age: 24, city: 'New York' },
    { age: 40, city: 'St. Paul' },
  ];

  const handleDownload = () => {
    downloadCsv({
      columns,
      data: rows,
    });
  };

  return <Button onClick={handleDownload}>Download CSV</Button>;
};

Editable Example

Table example

This example below creates and downloads a file named contacts.csv with two rows of data.

DataTable example

Use downloadCsv to export specific columns or filtered data from a DataTable. To learn more about downloading data in this component, see the Downloading data section.

Custom field separator

To change the delimiter, provide a custom fieldSeparator. For example, use ; for semicolon-separated values or \t for tab-separated values.

downloadCsv({
  columns: [
    { id: 'col1', header: 'Column 1' },
    { id: 'col2', header: 'Column 2' },
  ],
  data: [{ col1: 'A', col2: 'B' }],
  filename: 'export',
  fieldSeparator: ';', // Semicolon-separated
});

Custom column keys (header & accessor)

If your column definitions use different keys for labels and accessors, specify them with columnAccessorKey and columnLabelKey.

downloadCsv({
  columns: [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
  ],
  data: [
    { name: 'Alice', email: 'alice@example.com' },
    { name: 'Bob', email: 'bob@example.com' },
  ],
  filename: 'contacts',
  columnAccessorKey: 'key',
  columnLabelKey: 'name',
});