Export Persistence

Excel Export

Export grid data to Excel files.

NuGrid can export data to Excel format (.xlsx) with proper formatting for different data types.

Interactive Demo

Prerequisites

Install the optional write-excel-file package:

pnpm add write-excel-file

npm install write-excel-file

Basic Usage

Export using the grid ref:

<script setup lang="ts">
const gridRef = useTemplateRef('grid')

async function exportToExcel() {
  await gridRef.value?.excelExport('my-export', 'Sheet1')
}
</script>

<template>
  <UButton @click="exportToExcel">Export to Excel</UButton>

  <NuGrid ref="grid" :data="data" :columns="columns" />
</template>

Export Options

The excelExport method accepts different call signatures:

// Simple: just filename
gridRef.value?.excelExport('my-export')

// With sheet name
gridRef.value?.excelExport('my-export', 'My Sheet')

// Full options object
gridRef.value?.excelExport({
  filename: 'custom-name',
  sheetName: 'My Sheet',
  includeHeaders: true,
  visibleColumnsOnly: true,
  columnWidths: { name: 30, email: 40 },
})

Options Reference

Option	Type	Default	Description
`filename`	`string`	`'export'`	Output filename (without extension)
`sheetName`	`string`	`'Sheet1'`	Excel sheet name
`includeHeaders`	`boolean`	`true`	Include column headers
`visibleColumnsOnly`	`boolean`	`false`	Only export visible columns
`columnWidths`	`Record<string, number>`	-	Custom column widths

Supported Data Types

NuGrid automatically formats different data types in Excel:

Cell Data Type	Excel Format
`text`	Plain text
`number`	Numeric with appropriate precision
`currency`	Currency format with $ symbol
`date`	Date format (YYYY-MM-DD)
`boolean`	"Yes" / "No" text

Column Configuration for Export

Use cellDataType to ensure proper Excel formatting:

<script setup lang="ts">
const columns: NuGridColumn<Employee>[] = [
  { accessorKey: 'name', header: 'Name', cellDataType: 'text' },
  { accessorKey: 'salary', header: 'Salary', cellDataType: 'currency' },
  { accessorKey: 'hireDate', header: 'Hire Date', cellDataType: 'date' },
  { accessorKey: 'active', header: 'Active', cellDataType: 'boolean' },
]
</script>

Export Visible Columns Only

Export only the columns currently visible in the grid:

<script setup lang="ts">
async function exportFiltered() {
  await gridRef.value?.excelExport({
    filename: 'filtered-data',
    visibleColumnsOnly: true,
  })
}
</script>

Complete Example

<script setup lang="ts">
import type { NuGridColumn } from '#nu-grid/types'

interface Employee {
  id: number
  name: string
  email: string
  salary: number
  hireDate: string
  active: boolean
}

const gridRef = useTemplateRef('grid')

const data = ref<Employee[]>([
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', salary: 95000, hireDate: '2020-03-15', active: true },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', salary: 75000, hireDate: '2021-07-22', active: true },
  // ... more data
])

const columns: NuGridColumn<Employee>[] = [
  { accessorKey: 'id', header: 'ID', cellDataType: 'number' },
  { accessorKey: 'name', header: 'Name', cellDataType: 'text' },
  { accessorKey: 'email', header: 'Email', cellDataType: 'text' },
  {
    accessorKey: 'salary',
    header: 'Salary',
    cellDataType: 'currency',
    cell: ({ row }) => `$${row.original.salary.toLocaleString()}`,
  },
  {
    accessorKey: 'hireDate',
    header: 'Hire Date',
    cellDataType: 'date',
    cell: ({ row }) => new Date(row.original.hireDate).toLocaleDateString(),
  },
  { accessorKey: 'active', header: 'Active', cellDataType: 'boolean' },
]

async function handleExport() {
  await gridRef.value?.excelExport('employee-report', 'Employees')
}
</script>

<template>
  <div class="space-y-4">
    <UButton icon="i-lucide-file-spreadsheet" @click="handleExport">
      Export to Excel
    </UButton>

    <NuGrid
      ref="grid"
      :data="data"
      :columns="columns"
      :editing="{ enabled: true }"
    />
  </div>
</template>

When using multi-row display mode, each data row is exported as a single Excel row regardless of how many visual rows it spans in the grid.

Validation

Schema-based validation with Zod and custom row rules.

State Persistence

Save and restore grid state to localStorage.