Documentation

Cell Renderer

CodeSandbox

Cell renderers give you complete control over how data is displayed in your table cells. Using custom renderers, you can create rich, interactive elements like buttons, badges, progress bars, and more. With the expanded CellValue type supporting arrays and objects, you can now render complex data structures like tag lists, team member arrays, and nested object data.

💡 When to Use

For simple text formatting (currency, dates, percentages), consider using valueFormatter instead. It's more performant and easier to implement. Use cellRenderer when you need React components, custom styling, or interactive elements.

Basic Usage

Each column in your table can have its own cellRenderer function. This function receives information about the cell and returns either a ReactNode or a string to be rendered in the cell.

Cell Renderer Configuration

PropertyRequiredDescriptionExample
HeaderObject.cellRenderer
(params: CellRendererParams) => ReactNode | string
Optional
Custom function to render cell content with React components. Receives cell information and returns either a ReactNode or string for display. For simple text formatting (currency, dates, percentages), use valueFormatter instead for better performance.

Cell Renderer Parameters

CellRendererParams Interface

PropertyRequiredDescriptionExample
accessor
Accessor
Required
The column accessor/key for the cell being rendered
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)
rowPath
(string | number)[]
Optional
Array path through the nested data structure to reach this row. Each element is either a number (array index) or string (property name). Useful for accessing nested/hierarchical data.
theme
Theme
Required
Current theme of the table
value
CellValue
Required
The raw cell value
formattedValue
string | number | string[] | number[] | boolean | null | undefined
Optional
The formatted cell value (output from valueFormatter if defined). Use this for display purposes when you need both raw and formatted values.

💡 Pro Tips

  • Use value for quick access to the current cell's raw value (same as row[accessor])
  • Use formattedValue to access the valueFormatter output if one is defined, making it easy to wrap formatted text in custom components
  • Use row to access any data from the current row, not just the current cell - perfect for renderers that depend on multiple column values
  • New in v1.9.7: Use rowPath to access the path through nested data structures (e.g., [0, "teams", 1] for rows[0].teams[1])
  • New in v1.9.7: formattedValue now supports string[], number[], and boolean types for more flexible formatting

Row Object Structure

The row parameter passed to your cell renderer is a flat object containing all the row's data:

React TSX
1type Row = {
2  id: string | number;           // Unique identifier for the row
3  [accessor: Accessor]: CellValue; // All cell values accessible by column accessor
4  
5  // For hierarchical data (optional):
6  children?: Row[];              // Child rows (e.g., invoices array, stations array)
7};
8

9// CellValue now supports arrays and objects:
10type CellValue = string | number | boolean | undefined | null | string[] | number[] | Record<string, any>[];
11

12// Example row structure:
13{
14  id: "SALE-123",
15  repName: "John Doe",
16  dealSize: 15000,
17  isWon: true,
18  category: "Software",
19  tags: ["Enterprise", "SaaS"],           // string array
20  teamMembers: [                          // object array
21    { name: "Alice", role: "Manager" },
22    { name: "Bob", role: "Developer" }
23  ]
24}

To access a specific cell value, use row[accessor] directly. The row object is flat and contains all the data for that row.

Return Types

Your cellRenderer function should return one of the following:

  • String: A simple text value to display in the cell
    return "Hello, world!";
  • ReactNode: A React component for custom rendering
    return <div className="flex items-center"><span className="mr-2">⭐</span> Custom Content</div>;

Important Notes

  • Each column can have its own unique renderer
  • Columns without a cellRenderer will display their values as plain text
  • Avoid expensive operations in cell renderers as they run frequently
  • Consider memoizing complex components to improve performance
  • For simple text formatting, use valueFormatter instead for better performance