|
| 1 | +# Export Configuration |
| 2 | + |
| 3 | +TableCraft's `<DataTable>` includes a built-in export system that lets users download table data as **CSV** or **Excel (XLSX)** files. The `exportConfig` prop gives you full control over what gets exported and how. |
| 4 | + |
| 5 | +## Quick Start |
| 6 | + |
| 7 | +```tsx |
| 8 | +import { DataTable, defineExportConfig } from '@tablecraft/table'; |
| 9 | +import type { OrdersRow } from './generated/orders'; |
| 10 | + |
| 11 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 12 | + entityName: 'orders', |
| 13 | +}); |
| 14 | + |
| 15 | +<DataTable<OrdersRow> |
| 16 | + adapter={adapter} |
| 17 | + config={{ enableExport: true }} |
| 18 | + exportConfig={exportConfig} |
| 19 | +/> |
| 20 | +``` |
| 21 | + |
| 22 | +All visible columns are exported with their raw values by default. |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## Excluding Columns (`removeHeaders`) |
| 27 | + |
| 28 | +Use `removeHeaders` to hide specific columns from the export. All other visible columns are included automatically. |
| 29 | + |
| 30 | +```tsx |
| 31 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 32 | + entityName: 'orders', |
| 33 | + removeHeaders: ['deletedAt', 'tenantId'], |
| 34 | + // everything else is exported |
| 35 | +}); |
| 36 | +``` |
| 37 | + |
| 38 | +> **Why `removeHeaders`?** If you have 20 columns and only want to hide 2, it's much simpler to list the 2 to exclude than the 18 to include. |
| 39 | +
|
| 40 | +--- |
| 41 | + |
| 42 | +## Renaming Columns (`columnMapping`) |
| 43 | + |
| 44 | +Rename column headers in the export without affecting the UI. Works independently from `removeHeaders`. |
| 45 | + |
| 46 | +```tsx |
| 47 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 48 | + entityName: 'orders', |
| 49 | + removeHeaders: ['deletedAt'], |
| 50 | + columnMapping: { |
| 51 | + createdAt: 'Order Date', |
| 52 | + vatAmount: 'VAT (₹)', |
| 53 | + email: 'Customer Email', |
| 54 | + }, |
| 55 | +}); |
| 56 | +``` |
| 57 | + |
| 58 | +| In UI | In Export File | |
| 59 | +|-------|---------------| |
| 60 | +| `createdAt` | Order Date | |
| 61 | +| `vatAmount` | VAT (₹) | |
| 62 | +| `email` | Customer Email | |
| 63 | +| `status` | status (unchanged) | |
| 64 | + |
| 65 | +--- |
| 66 | + |
| 67 | +## Transforming Values (`transformFunction`) |
| 68 | + |
| 69 | +Format values before they're written to the file: |
| 70 | + |
| 71 | +```tsx |
| 72 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 73 | + entityName: 'orders', |
| 74 | + columnMapping: { createdAt: 'Order Date' }, |
| 75 | + transformFunction: (row) => ({ |
| 76 | + ...row, |
| 77 | + createdAt: row.createdAt |
| 78 | + ? new Date(row.createdAt).toLocaleDateString('en-IN') |
| 79 | + : '', |
| 80 | + total: `₹${Number(row.total).toFixed(2)}`, |
| 81 | + }), |
| 82 | +}); |
| 83 | +``` |
| 84 | + |
| 85 | +> Custom column renderers (JSX from `columnOverrides`) are **not** exported. Use `transformFunction` for custom text in the exported file. |
| 86 | +
|
| 87 | +--- |
| 88 | + |
| 89 | +## CSV / Excel Toggle |
| 90 | + |
| 91 | +```tsx |
| 92 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 93 | + entityName: 'orders', |
| 94 | + enableCsv: true, // default: true |
| 95 | + enableExcel: false, // disable Excel |
| 96 | +}); |
| 97 | +``` |
| 98 | + |
| 99 | +--- |
| 100 | + |
| 101 | +## Column Widths (Excel Only) |
| 102 | + |
| 103 | +```tsx |
| 104 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 105 | + entityName: 'orders', |
| 106 | + removeHeaders: ['deletedAt'], |
| 107 | + columnWidths: [ |
| 108 | + { wch: 8 }, // first column — narrow |
| 109 | + { wch: 30 }, // second column — wide |
| 110 | + { wch: 12 }, // third column — medium |
| 111 | + ], |
| 112 | +}); |
| 113 | +``` |
| 114 | + |
| 115 | +--- |
| 116 | + |
| 117 | +## Cross-Page Export |
| 118 | + |
| 119 | +When users select rows across multiple pages: |
| 120 | +- **Same-page selections** — uses in-memory data (no API call) |
| 121 | +- **Cross-page selections** — fetches selected IDs from backend via `queryByIds` |
| 122 | + |
| 123 | +This is automatic — no extra config needed. |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +## Type-Safe Helper: `defineExportConfig<T>()` |
| 128 | + |
| 129 | +For configs defined outside JSX, use the helper for autocomplete: |
| 130 | + |
| 131 | +```tsx |
| 132 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 133 | + entityName: 'orders', |
| 134 | + removeHeaders: ['deletedAt'], // ← autocomplete works |
| 135 | + columnMapping: { email: 'Email' }, // ← autocomplete works |
| 136 | +}); |
| 137 | +``` |
| 138 | + |
| 139 | +Inline usage within `<DataTable<OrdersRow>>` is also type-safe — no helper needed. |
| 140 | + |
| 141 | +--- |
| 142 | + |
| 143 | +## Full Example |
| 144 | + |
| 145 | +```tsx |
| 146 | +import { DataTable, defaultColumnOrder, defineExportConfig } from '@tablecraft/table'; |
| 147 | +import { createOrdersAdapter, type OrdersRow } from './generated/orders'; |
| 148 | +import type { OrdersColumn } from './generated/orders'; |
| 149 | + |
| 150 | +const exportConfig = defineExportConfig<OrdersRow>()({ |
| 151 | + entityName: 'orders', |
| 152 | + removeHeaders: ['deletedAt', 'tenantId'], |
| 153 | + columnMapping: { |
| 154 | + createdAt: 'Order Date', |
| 155 | + vatAmount: 'VAT Amount', |
| 156 | + itemCount: 'Items', |
| 157 | + }, |
| 158 | + transformFunction: (row) => ({ |
| 159 | + ...row, |
| 160 | + createdAt: row.createdAt |
| 161 | + ? new Date(row.createdAt).toLocaleDateString('en-IN') |
| 162 | + : '', |
| 163 | + total: `₹${Number(row.total).toFixed(2)}`, |
| 164 | + }), |
| 165 | +}); |
| 166 | + |
| 167 | +export function OrdersPage() { |
| 168 | + const adapter = createOrdersAdapter({ baseUrl: '/api/engine' }); |
| 169 | + |
| 170 | + return ( |
| 171 | + <DataTable<OrdersRow> |
| 172 | + adapter={adapter} |
| 173 | + config={{ enableExport: true }} |
| 174 | + exportConfig={exportConfig} |
| 175 | + defaultColumnOrder={defaultColumnOrder<OrdersColumn>([ |
| 176 | + 'id', 'status', 'email', 'total', 'vatAmount', 'itemCount', 'createdAt', |
| 177 | + ])} |
| 178 | + /> |
| 179 | + ); |
| 180 | +} |
| 181 | +``` |
0 commit comments