# Cell Formatting
URL: https://pro.rv-grid.com/guides/excel-export/cell-formatting/
Source: src/content/docs/guides/excel-export/cell-formatting.mdx
Description: Format Excel export cells, formulas, column types, grouped headers, and merge spans.
Use `column.excelExport` when workbook output needs values or styles that differ from the rendered grid. Export formatting is data-source based and runs during export only.

## Column Export Callbacks

```ts
import type { ColumnRegular } from '@revolist/revogrid';

const columns: ColumnRegular[] = [
  {
    prop: 'price',
    name: 'Price',
    excelExport: {
      columnProperties: ({ value }) => ({
        value,
        fontWeight: 'bold',
        backgroundColor: 'E8EEF9',
      }),
      cellProperties: ({ value, rowType }) => ({
        value,
        type: Number,
        format: '$#,##0.00',
        align: 'right',
        fontWeight: rowType === 'rowPinEnd' ? 'bold' : undefined,
      }),
    },
  },
];
```

`columnProperties` formats the generated header cell. `cellProperties` formats body, pinned-top, and pinned-bottom cells.

`cellProperties` receives:

| Field | Meaning |
| --- | --- |
| `value` | Prepared export value after formula evaluation |
| `rawValue` | Original source value for the column |
| `model` | Original source row object |
| `rowIndex` | Index inside its source row segment |
| `rowType` | `rowPinStart`, `rgRow`, or `rowPinEnd` |
| `column` | Current column definition |
| `columnIndex` | Export column index |
| `revogrid` | Grid element |
| `providers` | Runtime plugin providers |

Callbacks can return:

- a primitive value to replace the exported value
- a cell object with `value` and style fields
- a style-only object, which keeps the prepared value
- `undefined`, which keeps the default prepared cell

## Style Fields

Common workbook style fields include:

| Field | Example |
| --- | --- |
| `fontFamily`, `fontSize`, `fontWeight`, `fontStyle` | text styling |
| `textColor`, `backgroundColor`, `fillPatternColor` | colors |
| `borderColor`, `leftBorderColor`, `rightBorderColor`, `topBorderColor`, `bottomBorderColor` | borders |
| `align`, `alignVertical`, `wrap`, `textRotation`, `indent` | alignment |
| `format` | number/date format |
| `height`, `columnSpan`, `rowSpan` | layout |

The bundled `write-excel-file` provider accepts `#E8EEF9` and bare RGB hex values such as `E8EEF9` for known color fields. Bare colors are prefixed before the provider calls `write-excel-file`.

Optional providers map this structural shape to their own workbook library. Unsupported fields may be ignored by a custom provider.

## Formula Export

Formula cells are evaluated by default. To export workbook formulas instead of evaluated values, attach the formula helper:

```ts
import { createFormulaExcelExportCellProperties } from '@revolist/revogrid-pro';

const formulaProperties = createFormulaExcelExportCellProperties({
  includeEvaluatedResult: true,
});

const columns = [
  {
    prop: 'total',
    name: 'Total',
    excelExport: {
      cellProperties: formulaProperties,
    },
  },
];
```

When `includeEvaluatedResult` is enabled, providers that support cached formula results can receive both the formula and the prepared result.

## External Column Type Helpers

Date, numeral, and select column packages are optional app dependencies, so Pro exposes explicit Excel export helpers instead of importing those packages automatically:

```ts
import {
  createDateExcelExportColumnOptions,
  createNumeralExcelExportColumnOptions,
  createSelectExcelExportColumnOptions,
} from '@revolist/revogrid-pro';

const columns = [
  {
    prop: 'createdAt',
    name: 'Created',
    columnType: 'date',
    excelExport: createDateExcelExportColumnOptions({ format: 'yyyy-mm-dd' }),
  },
  {
    prop: 'amount',
    name: 'Amount',
    columnType: 'currency',
    excelExport: createNumeralExcelExportColumnOptions({ format: '$#,##0.00' }),
  },
  {
    prop: 'status',
    name: 'Status',
    columnType: 'select',
    source: [
      { value: 'open', label: 'Open' },
      { value: 'closed', label: 'Closed' },
    ],
    labelKey: 'label',
    valueKey: 'value',
    excelExport: createSelectExcelExportColumnOptions({
      column: {
        prop: 'status',
        source: [
          { value: 'open', label: 'Open' },
          { value: 'closed', label: 'Closed' },
        ],
        labelKey: 'label',
        valueKey: 'value',
      },
    }),
  },
];
```

Date helpers convert valid date-like values to `Date` cells. Numeral helpers convert finite numbers and numeric strings to number cells. Select helpers export the user-facing label for stored values.

## Grouped Headers And Cell Merge

Grouped column headers are applied automatically when the grid uses a grouped `columns` tree. Group header rows are inserted before the flattened leaf header row.

Cell merge spans are applied automatically when the grid has `cellMerge` data. The export transform maps grid row and column segment coordinates into provider matrix coordinates, accounting for generated header rows.

The built-in `write-excel-file` provider and ExcelJS adapter consume `columnSpan` and `rowSpan` values from `cellRows`. Custom providers can also read merge metadata from `context.exportMetadata.cellMerge`.

## Provider Context

Custom providers and transformers receive a prepared `ExcelExportProviderContext`:

| Field | Purpose |
| --- | --- |
| `cellRows` | Provider-ready matrix with header rows and formatted cells |
| `rows` | Plain row objects keyed by column prop, with formulas evaluated |
| `sourceRows` | Original row models with row index and row segment metadata |
| `headerRowsCount` | Number of generated header rows before data rows in `cellRows` |
| `gridDerivedOptions` | Width and freeze-pane hints inferred from current grid state |
| `exportMetadata` | Feature metadata such as grouped headers and cell merge ranges |

Use `cellRows` for formatted workbook output. Use `rows` for simple JSON-style providers that do not need formatting.

## Export Transformers

Use `exportTransformers` for final app-owned changes to the provider context:

```ts
grid.exportExcel = {
  exportTransformers: [
    (context) => ({
      exportMetadata: {
        generatedBy: 'orders-report',
      },
      providerOptions: {
        hideGridLines: true,
      },
    }),
  ],
};
```

Grid-level transformers run before per-export transformers:

```ts
await excel.export({
  exportTransformers: [
    (context) => {
      context.cellRows[0][0] = { value: 'Exported Orders', fontWeight: 'bold' };
    },
  ],
});
```
