Documentation

Value Formatter

Value formatters provide a simple way to format cell values for display without changing the underlying data. Use them for currency, dates, percentages, and other formatted text. For complex rendering with React components, use cellRenderer instead.

Basic Usage

Each column in your table can have its own valueFormatter function. This function receives information about the cell and returns a formatted string or number for display.

Value Formatter Configuration

Property	Required	Description

`HeaderObject.valueFormatter` (props: ValueFormatterProps) => string \| number	Optional	Function to format the cell value for display without affecting the underlying data. Returns a string or number that will be displayed in the cell. Useful for currency, dates, percentages, and other formatted text.
`HeaderObject.useFormattedValueForClipboard` boolean	Optional	When true, cells copy the formatted value (with symbols, formatting) when users press Ctrl+C/Cmd+C. Defaults to true when valueFormatter exists (v1.8.6+), or false if no valueFormatter. Useful for copying currency with $ symbols, percentages with %, or formatted dates.
`HeaderObject.useFormattedValueForCSV` boolean	Optional	When true, CSV exports use the formatted value from valueFormatter instead of raw data. Defaults to true when valueFormatter exists (v1.8.6+), or false if no valueFormatter. Perfect for human-readable reports and spreadsheets. Note: exportValueGetter takes precedence if provided.
`HeaderObject.exportValueGetter` (props: ExportValueProps) => string \| number	Optional	Custom function to provide completely different values for CSV export. Takes precedence over useFormattedValueForCSV. Useful for adding codes, identifiers, or transforming data specifically for spreadsheet compatibility.

Value Formatter Parameters

ValueFormatterProps Interface

Property	Required	Description

`accessor` Accessor	Required	The column accessor/key for the cell being formatted
`colIndex` number	Required	The column index (0-based)
`row` Row	Required	The complete row object containing all data for this row
`rowIndex` number	Required	The row index (0-based)
`value` CellValue	Required	The raw cell value to be formatted

💡 Pro Tip

Use valueFormatter for simple text formatting (currency, dates, percentages). Use cellRenderer when you need React components, custom styling, or interactive elements.

Common Use Cases

Currency Formatting

Format numeric values as currency with proper locale formatting:

React TSX

Copy

1{
2  accessor: "price",
3  label: "Price",
4  type: "number",
5  valueFormatter: ({ value }) => {
6    return `$${(value as number).toLocaleString("en-US", {
7      minimumFractionDigits: 2,
8      maximumFractionDigits: 2,
9    })}`;
10  }
11}
12
13// Display: $1,234.56 (from raw value: 1234.56)

Date Formatting

Format date strings or timestamps into readable dates:

React TSX

Copy

1{
2  accessor: "createdDate",
3  label: "Created",
4  type: "date",
5  valueFormatter: ({ value }) => {
6    const date = new Date(value as string);
7    return date.toLocaleDateString("en-US", {
8      month: "short",
9      day: "numeric",
10      year: "numeric",
11    });
12  }
13}
14
15// Display: Dec 25, 2024 (from raw value: "2024-12-25")

Percentage Formatting

Display decimal values as percentages:

React TSX

Copy

1{
2  accessor: "profitMargin",
3  label: "Margin",
4  type: "number",
5  valueFormatter: ({ value }) => {
6    return `${((value as number) * 100).toFixed(1)}%`;
7  }
8}
9
10// Display: 15.5% (from raw value: 0.155)

Conditional Formatting

Format values differently based on conditions:

React TSX

Copy

1{
2  accessor: "balance",
3  label: "Balance",
4  type: "number",
5  valueFormatter: ({ value }) => {
6    const balance = value as number;
7    if (balance === 0) return "—";
8    if (balance < 0) return `(${Math.abs(balance).toFixed(2)})`;
9    return `$${balance.toFixed(2)}`;
10  }
11}
12
13// Display: $100.00, (50.00), or —

Using Multiple Row Values

Access other column values from the same row for combined formatting:

React TSX

Copy

1{
2  accessor: "firstName",
3  label: "Name",
4  type: "string",
5  valueFormatter: ({ value, row }) => {
6    const firstName = value as string;
7    const lastName = row.lastName as string;
8    return `${firstName} ${lastName}`;
9  }
10}
11
12// Display: John Doe (from firstName: "John", lastName: "Doe")

Clipboard and CSV Formatting

Control how formatted values are copied to clipboard and exported to CSV files. Starting in v1.8.6, both useFormattedValueForClipboard and useFormattedValueForCSV default to true when a valueFormatter exists, reducing boilerplate code.

✨ Auto-Default Behavior (v1.8.6+)

When you define a valueFormatter, formatted values are automatically used for clipboard copy and CSV exports. You no longer need to explicitly set these flags to true!

To use raw values: Explicitly set useFormattedValueForClipboard: false or useFormattedValueForCSV: false

Formatted Clipboard Copy

With a valueFormatter, formatted values are automatically copied when users press Ctrl+C or Cmd+C:

React TSX

Copy

1{
2  accessor: "salary",
3  label: "Salary",
4  valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}`
5  // useFormattedValueForClipboard: true (automatically defaults to true)
6}
7
8// User copies cell: Gets "$85,000" instead of 85000
9// Perfect for pasting into reports or presentations
10
11// To copy raw values instead, explicitly set to false:
12// useFormattedValueForClipboard: false

CSV Export Formatting

Control CSV export values with two options:

Option 1: Automatic Formatting (v1.8.6+)

When a valueFormatter is defined, CSV exports automatically use the formatted value:

React TSX

Copy

1{
2  accessor: "margin",
3  valueFormatter: ({ value }) => `${(value * 100).toFixed(1)}%`
4  // useFormattedValueForCSV: true (automatically defaults to true)
5}
6// CSV exports: "92.5%" instead of 0.925
7
8// To export raw values, explicitly set to false:
9// useFormattedValueForCSV: false

Option 2: exportValueGetter (Higher Priority)

Provide completely custom values for CSV export:

React TSX

Copy

1{
2  accessor: "department",
3  valueFormatter: ({ value }) => capitalize(value),
4  exportValueGetter: ({ value }) => {
5    const codes = { engineering: "ENG", sales: "SLS" };
6    return `${capitalize(value)} (${codes[value]})`;
7  }
8}
9// Display: "Engineering"
10// CSV exports: "Engineering (ENG)"

Priority System

Clipboard: useFormattedValueForClipboard + valueFormatter → Chart formatting (comma-separated) → Raw value
CSV Export: exportValueGetter → useFormattedValueForCSV + valueFormatter → Raw value

When to Use Value Formatter vs Cell Renderer

✓Use valueFormatter for:

Currency formatting ($1,234.56)
Date formatting (Dec 25, 2024)
Percentage display (15.5%)
Number formatting (1,000,000)
Simple text transformations
Concatenating values from the same row
Better performance for simple formatting

→Use cellRenderer for:

React components (badges, buttons, icons)
Custom styling and colors
Interactive elements (clicks, hovers)
Complex layouts (flexbox, grids)
Images and media
Progress bars, charts, visualizations
Array or object data rendering

Important Notes

valueFormatter only affects display - the underlying data remains unchanged
If both valueFormatter and cellRenderer are provided, cellRenderer takes precedence
valueFormatter is more performant for simple text formatting
Return values must be strings or numbers, not React components

Examples Comparison

Here's the same formatting task using both approaches:

Using valueFormatter (Recommended for simple text)

React TSX

Copy

1{
2  accessor: "price",
3  label: "Price",
4  type: "number",
5  valueFormatter: ({ value }) => {
6    return `$${(value as number).toFixed(2)}`;
7  }
8}

Using cellRenderer (For custom styling)

React TSX

Copy

1{
2  accessor: "price",
3  label: "Price",
4  type: "number",
5  cellRenderer: ({ value }) => {
6    const price = value as number;
7    return (
8      <span style={{ 
9        color: price > 100 ? '#10b981' : '#6b7280',
10        fontWeight: 'bold'
11      }}>
12        ${price.toFixed(2)}
13      </span>
14    );
15  }
16}

Both approaches display the same text, but cellRenderer allows for custom styling and React components at the cost of slightly more complexity.