# useDataExport
URL: /docs/native/hooks/use-data-export

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.

## Installation

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

**Dependencies:**
- [expo-file-system (optional)](https://www.npmjs.com/package/expo-file-system)
- [expo-sharing (optional)](https://www.npmjs.com/package/expo-sharing)

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`](/docs/native/hooks/use-docyrus-data-export).

`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

```tsx
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
  );
}
```

### 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&lt;TData&gt;

| 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. |