useDataExport

Client-side export of already-loaded rows to CSV, JSON, Markdown or Excel on React Native. Projects rows through a column list, writes the file into the cache directory and opens the share sheet. API-aligned with the web useDataExport.

Edit on GitHubEditllms.txt

iOSAndroidExpo Go

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-data-export

Required Packages(2 packages)

pnpm add expo-file-system (optional) expo-sharing (optional)

The hook needs no Docyrus client. It works on rows you already hold, such as the rows of a list, a grid page or generated sample data. For a full server-side export of a data source, use useDocyrusDataExport.

expo-file-system (SDK 54+ File / Paths API) and expo-sharing are optional peers, loaded lazily through the internal lib/native-export helpers. Without expo-file-system, exportData resolves null and writes nothing. Without expo-sharing, the file is written but the share sheet does not open.

Usage

import { Button } from '@/components/docyrus-native/button';
import { useDataExport, type DataExportColumn } from '@/hooks/docyrus-native/use-data-export';

type Contact = { id: string; name: string; email: string; company?: { name: string } };

const columns: DataExportColumn<Contact>[] = [
  { id: 'name', header: 'Name' },
  { id: 'email', header: 'Email' },
  { id: 'company', header: 'Company', accessor: row => row.company?.name ?? '' }
];

export function ExportContacts({ rows }: { rows: Contact[] }) {
  const { exportData, isExporting } = useDataExport({ columns, fileName: 'contacts' });

  return (
    <Button loading={isExporting} onPress={() => void exportData(rows, 'xlsx')}>
      Export to Excel
    </Button>
  );
}

Formats

Format	Extension	Output
`csv`	`.csv`	RFC 4180 quoting, CRLF line endings, UTF-8 BOM by default (`csvBom`).
`json`	`.json`	Array of projected objects keyed by column `id`, pretty-printed.
`markdown`	`.md`	GitHub table. Pipes and backslashes are escaped and newlines become `<br />`.
`xlsx`	`.xlsx`	Single sheet with a bold, frozen header row. Numbers, booleans and dates are typed cells, and objects are JSON strings.

Without a formatter, primitives are written as they are, dates as ISO strings, and objects / arrays through JSON.stringify.

API Reference

Options (`UseDataExportOptions<TData>`)

Option	Type	Default	Description
`columns`	`DataExportColumn<TData>[]`	—	Column projection. Order is kept in the output (required).
`fileName`	`string`	`'export'`	File name without extension. Invalid characters are removed.
`sheetName`	`string`	`'Sheet1'`	Sheet name for `xlsx`.
`csvBom`	`boolean`	`true`	Prepend a UTF-8 BOM to CSV output so Excel detects the encoding.
`share`	`boolean`	`true`	Native: open the share sheet after writing. `false` only writes the file and returns its `uri`.
`dialogTitle`	`string`	the file name	Native: title of the Android share chooser.

DataExportColumn<TData>

Field	Type	Description
`id`	`string`	Stable column id, also the JSON key (required).
`header`	`string`	Header label for CSV, Markdown and Excel (required).
`accessor`	`(row: TData) => unknown`	Raw value. Defaults to `row[id]`.
`formatter`	`(value: unknown, row: TData) => string`	Runs after `accessor` to produce the written value.

Result (`UseDataExportResult<TData>`)

Field	Type	Description
`exportData`	`(rows: TData[], format: DataExportFormat) => Promise<DataExportResult \| null>`	Project, write and share. Resolves `null` when `expo-file-system` is missing.
`isExporting`	`boolean`	True while a file is being written.

DataExportResult

Field	Type	Description
`mimeType`	`string`	MIME type of the file.
`extension`	`string`	Extension including the leading dot.
`fileName`	`string`	`<fileName><extension>`.
`uri`	`string`	Native: local `file://` URI in the cache directory.

Differences from web

Web builds a Blob and clicks an <a download>. Native writes the file into the cache directory and opens the share sheet, so the user can save it to Files, send it or open it in another app.
Web writes Excel with exceljs, which needs Node Buffer / stream polyfills that Metro does not ship. Native uses a zero-dependency OOXML writer (buildSimpleXlsx in the internal lib/native-export), which is also used by the pivot-grid exporter.
Native adds the share and dialogTitle options and the uri field on the result. exportData can resolve null.

Type Exports

Type	Description
`UseDataExportOptions`	Hook options.
`UseDataExportResult`	Hook result.
`DataExportColumn`	Column projection entry.
`DataExportFormat`	`'csv' \| 'json' \| 'markdown' \| 'xlsx'`.
`DataExportResult`	Written file metadata.

useDataExport

On this page