Documentation

Value Formatter

StackBlitz

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

PropertyRequiredDescriptionExample
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

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

Date Formatting

Format date strings or timestamps into readable dates.

Percentage Formatting

Display decimal values as percentages.

Conditional Formatting

Format values differently based on conditions.

Using Multiple Row Values

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

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.

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.

Option 2: exportValueGetter (Higher Priority)

Provide completely custom values for CSV export.

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:

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