Documentation

Value Formatter

CodeSandbox

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.

Value Formatter Parameters

ValueFormatterProps Interface

PropertyRequiredDescriptionExample
accessor
Accessor
Required
The column accessor string identifying which column this cell belongs to.
colIndex
number
Required
The zero-based index of the column within the table.
row
Row
Required
The complete row object containing all data for this row. Access cell values using row[accessor].
rowIndex
number
Required
The zero-based index of the row within the table.
value
CellValue
Required
The raw cell value from the data.

💡 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
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
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
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
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
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")

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