Documentation

API Reference

Complete reference for all SimpleTable component props and HeaderObject configuration options.

SimpleTable Props

These are all the props available for the main SimpleTable component.

SimpleTable Component Props

Property	Required	Description

`defaultHeaders` HeaderObject[]	Required	Array of column definitions that specify the structure of your table.
`rows` Row[]	Required	Array of data objects to display in the table. Each object represents a row.
`rowIdAccessor` Accessor	Required	Property name to use as row ID. This is crucial for proper row tracking, selection, and updates.
`height` string	Optional	Height of the table container.
`rowHeight` number	Optional	Height of each individual row in pixels.
`allowAnimations` boolean	Optional	Beta feature! This feature is not yet fully tested and may not work as expected. Use at your own risk. Flag for allowing animations throughout the table.
`cellUpdateFlash` boolean	Optional	Flag for flash animation after cell update.
`columnReordering` boolean	Optional	Enable column reordering by drag and drop.
`columnResizing` boolean	Optional	Enable column resizing functionality.
`editColumns` boolean	Optional	Flag for column editing via column editor panel.
`editColumnsInitOpen` boolean	Optional	Flag for opening the column editor when the table is loaded.
`expandAll` boolean	Optional	Flag for expanding all rows by default (for grouped rows).
`expandIcon` ReactNode	Optional	Icon for expandable rows (will rotate on expand/collapse).
`externalFilterHandling` boolean	Optional	Flag to let consumer handle filter logic completely.
`externalSortHandling` boolean	Optional	When true, completely disables internal sorting logic. The table will not sort data internally - you must provide pre-sorted data via the rows prop.
`initialSortColumn` string	Optional	Sets the column to sort by on initial table load. Provide the accessor of the column you want to sort by default. Works with both internal and external sorting.
`initialSortDirection` "ascending" \| "descending"	Optional	Sets the sort direction for the initial sort. Defaults to 'ascending' if not specified. Only applies when initialSortColumn is also set.
`hideFooter` boolean	Optional	Flag for hiding the table footer.
`onFilterChange` (filters: TableFilterState) => void	Optional	Callback function triggered when filter configuration changes. Receives the current filter state with all active filters.
`onLoadMore` () => void	Optional	Callback function triggered when user scrolls near the bottom of the table to load more data. Useful for implementing infinite scrolling or paginated data loading.
`onSortChange` (sort: SortConfig \| null) => void	Optional	Callback function triggered when sort configuration changes. Receives the current sort configuration or null if no sorting is applied.
`rowGrouping` string[]	Optional	Array of property names that define row grouping hierarchy.
`onRowGroupExpand` (props: OnRowGroupExpandProps) => void	Optional	Callback function triggered when a grouped row is expanded or collapsed. Provides detailed information about the row, depth level, and grouping context, plus helper functions for managing loading, error, and empty states. The rowIndexPath array provides a direct path to update nested data. Perfect for implementing lazy-loading of hierarchical data with built-in state management.
`loadingStateRenderer` string \| ReactNode	Optional	Custom content to display when a row is in loading state (set via setLoading in onRowGroupExpand). Can be a simple string or React component. Shown in place of row children while data is being fetched. If not provided, a default skeleton loading animation will be displayed automatically.
`errorStateRenderer` string \| ReactNode	Optional	Custom content to display when a row has an error state (set via setError in onRowGroupExpand). Can be a simple string or React component. Shown in place of row children when data fetching fails.
`emptyStateRenderer` string \| ReactNode	Optional	Custom content to display when a row has no children data (set via setEmpty in onRowGroupExpand). Can be a simple string or React component. Shown when data fetch succeeds but returns zero results.
`canExpandRowGroup` (row: Row) => boolean	Optional	Callback function to conditionally control whether a specific row group can be expanded. Return true to allow expansion, false to disable it. Useful for implementing permission-based access, hiding empty groups, or preventing expansion based on business logic.
`rowsPerPage` number	Optional	Number of rows per page for pagination.
`onPageChange` (page: number) => void \| Promise<void>	Optional	Callback function triggered when page changes. Useful for server-side pagination to fetch data for the new page.
`serverSidePagination` boolean	Optional	Flag to disable internal pagination slicing. When true, the table expects you to provide pre-paginated data via the rows prop and handle pagination externally.
`totalRowCount` number	Optional	Total number of rows available on the server (for server-side pagination). Used to calculate total pages and display correct pagination information.
`selectableCells` boolean	Optional	Enable cell selection functionality.
`copyHeadersToClipboard` boolean	Optional	When true, includes column headers as the first row when copying selected cells to clipboard. Defaults to false.
`selectableColumns` boolean	Optional	Flag for selectable column headers.
`shouldPaginate` boolean	Optional	Flag for enabling pagination.
`isLoading` boolean	Optional	When set to true, all table cells will render skeleton loaders instead of actual data. Provides visual feedback while data is being fetched from the server.
`theme` Theme	Optional	Theme configuration for the table styling.
`useOddColumnBackground` boolean	Optional	Flag for using alternating column background colors.
`useHoverRowBackground` boolean	Optional	Flag for using hover row background highlighting.
`useOddEvenRowBackground` boolean	Optional	Flag for using odd/even row background colors.
`enableRowSelection` boolean	Optional	Enable row selection functionality with checkboxes.
`onRowSelectionChange` (props: RowSelectionChangeProps) => void	Optional	Callback function triggered when row selection changes.
`onCellClick` (props: CellClickProps) => void	Optional	Callback function triggered when a cell is clicked. Provides detailed information about the clicked cell including its position, value, and containing row.
`onCellEdit` (props: CellChangeProps) => void	Optional	Callback function triggered when a cell is edited. Provides the edited cell information including the new value, row, and column accessor.
`onColumnSelect` (header: HeaderObject) => void	Optional	Callback when a column is selected/clicked. Provides the complete HeaderObject of the selected column.
`enableHeaderEditing` boolean	Optional	Flag for enabling header label editing when clicking already active headers.
`onHeaderEdit` (header: HeaderObject, newLabel: string) => void	Optional	Callback when a header is edited. Receives the HeaderObject and the new label value.
`onColumnOrderChange` (newHeaders: HeaderObject[]) => void	Optional	Callback when column order changes (through drag and drop reordering). Receives the new headers array in the updated order.
`columnBorders` boolean	Optional	Flag for showing column borders.
`headerDropdown` HeaderDropdown	Optional	Custom dropdown component for headers.
`footerRenderer` (params: FooterRendererProps) => ReactNode	Optional	Custom function to render the table footer. Receives pagination state and navigation handlers, allowing complete customization of footer appearance and behavior.
`rowButtons` RowButton[]	Optional	Array of buttons to show in each row.
`selectionColumnWidth` number	Optional	Width of the selection column (defaults to 42).
`headerExpandIcon` ReactNode	Optional	Custom icon component for the expand state of collapsible column headers. Shows when a column group can be expanded to reveal child columns.
`headerCollapseIcon` ReactNode	Optional	Custom icon component for the collapse state of collapsible column headers. Shows when a column group can be collapsed to hide child columns.
`className` string	Optional	CSS class name to apply to the table container element.
`columnEditorPosition` ColumnEditorPosition	Optional	Position of the column editor panel when editColumns is enabled.
`columnEditorText` string	Optional	Custom text label for the column editor panel.
`onGridReady` () => void	Optional	Callback function triggered when the table grid is fully initialized and ready.
`onNextPage` OnNextPage	Optional	Custom handler for pagination next page action.
`tableRef` MutableRefObject<TableRefType \| null>	Optional	React ref object to access table methods and state programmatically. Provides access to methods like exportToCSV and updateData.
`includeHeadersInCSVExport` boolean	Optional	When true, includes column headers as the first row in CSV exports. Defaults to true.
`tableEmptyStateRenderer` ReactNode	Optional	Custom content to display in the table body when there are no rows to display. This can occur when filters return no results or when no data is provided.

HeaderObject Configuration

These are all the properties available when defining column headers in the defaultHeaders array.

Header Object Properties

Property	Required	Description

`accessor` Accessor	Required	The key to access data in your row objects. Must match a property in your data. Supports nested properties using dot notation (e.g., 'user.profile.name' or 'latest.rank').
`label` string	Required	The display name shown in the column header.
`width` number \| string	Required	Column width. Can be pixels, string with units, or flexible units like '1fr'.
`aggregation` AggregationConfig	Optional	Configuration for data aggregation when rows are grouped.
`align` string	Optional	Text alignment for the column content. Options: left center right
`type` enum	Optional	Data type for proper formatting and sorting behavior. Chart types render array data as inline visualizations. Options: string number boolean date enum lineAreaChart barChart other
`chartOptions` ChartOptions	Optional	Customization options for chart columns (lineAreaChart and barChart). Configure dimensions, colors, scaling, stroke width, and other visual properties. See the chart-options section for detailed options.
`minWidth` number \| string	Optional	Minimum width constraint for the column.
`isSortable` boolean	Optional	Enable sorting for this column.
`filterable` boolean	Optional	Enable filtering for this column.
`isEditable` boolean	Optional	Enable inline editing for this column.
`hide` boolean	Optional	Hide this column from display.
`disableReorder` boolean	Optional	Prevent this column from being reordered.
`expandable` boolean	Optional	Make this column expandable for row grouping.
`pinned` Pinned	Optional	Pin this column to left or right side. Options: left right
`children` HeaderObject[]	Optional	Child columns for nested header structure.
`enumOptions` EnumOption[]	Optional	Options for enum type columns (dropdown values).
`cellRenderer` ({ accessor, colIndex, row, theme, value, formattedValue }: CellRendererProps) => ReactNode \| string	Optional	Custom render function for cell content. Receives both raw and formatted values for flexible rendering. Use this for React components, custom styling, or interactive elements. For simple text formatting (currency, dates), use valueFormatter instead for better performance.
`valueFormatter` (props: ValueFormatterProps) => string \| number \| string[] \| number[]	Optional	Function to format the cell value for display without affecting the underlying data. Returns a string, number, or arrays of strings/numbers (v1.9.4+). Use this for currency, dates, percentages, and other simple text formatting. For React components or custom styling, use cellRenderer instead.
`valueGetter` (props: ValueGetterProps) => CellValue	Optional	Function to extract or compute values dynamically for sorting operations. Useful when the displayed value differs from the sorting value, or when sorting by nested properties. The extracted value is used for sorting while the display value (from valueFormatter or cellRenderer) remains unchanged.
`comparator` (props: ComparatorProps) => number	Optional	Custom sorting function with full control over the sorting logic. Receives both row objects and sort direction, allowing complex multi-field sorting, metadata access, or domain-specific rules. Takes precedence over valueGetter and default sorting.
`useFormattedValueForClipboard` boolean	Optional	When true, cells copy the formatted value (from valueFormatter) when users press Ctrl+C/Cmd+C. When false (default), cells copy the raw underlying data. Useful for copying currency with $ symbols, percentages with %, or formatted dates.
`useFormattedValueForCSV` boolean	Optional	When true, CSV exports use the formatted value from valueFormatter instead of raw data. Perfect for human-readable reports. Note: exportValueGetter takes precedence if provided.
`exportValueGetter` (props: ExportValueProps) => string \| number	Optional	Custom function to provide completely different values specifically for CSV export. Takes highest priority over useFormattedValueForCSV. Ideal for adding codes, identifiers, or transforming data for spreadsheet compatibility.
`headerRenderer` ({ accessor, colIndex, header }: { accessor: Accessor; colIndex: number; header: HeaderObject; }) => ReactNode \| string	Optional	Custom render function for header content.
`collapsible` boolean	Optional	Makes this column group collapsible. When true, users can click an arrow icon to collapse/expand the column group. Must have children columns.
`showWhen` ShowWhen ("parentCollapsed" \| "parentExpanded" \| "always")	Optional	Controls when a child column is visible in collapsible groups. Can be "parentCollapsed" (only visible when collapsed), "parentExpanded" (only visible when expanded), or "always" (visible in both states). Default is "parentExpanded".
`tooltip` string	Optional	Tooltip text that appears when hovering over the column header. Provides helpful context about the column's purpose or data.
`singleRowChildren` boolean	Optional	When true, displays the parent header and child headers horizontally in the same row (side-by-side) instead of the default nested structure where parent appears above children. This makes the parent header appear as a regular column that can collapse its sibling columns, rather than looking like a group header. Only applies to collapsible columns.
`collapseDefault` boolean	Optional	When true, this column starts collapsed on initial render. Only applies to columns with collapsible set to true. Useful for showing a compact view by default.
`excludeFromRender` boolean	Optional	When true, excludes this column from the rendered table. The column data is still available for CSV export. Useful for ID columns or metadata that should be exported but not displayed.
`excludeFromCsv` boolean	Optional	When true, excludes this column from CSV exports. The column is still displayed in the table. Useful for sensitive data or UI-only columns that shouldn't be exported.

Type Definitions

All union type values and object type properties used in SimpleTable.

EnumOption

Property	Required	Description

`label` string	Required	Display text shown in the dropdown
`value` string	Required	Actual value stored in the data

AggregationConfig

Property	Required	Description

`type` AggregationType	Required	The aggregation function to use
`parseValue` (value: any) => number	Optional	Function to parse string values to numbers (e.g., '$15.0M' to 15000000)
`formatResult` (value: number) => string	Optional	Function to format the aggregated result back to string
`customFn` (values: any[]) => any	Optional	Custom aggregation function (only when type is 'custom')

RowSelectionChangeProps

Property	Required	Description

`row` Row	Required	The complete row object that was selected or deselected
`isSelected` boolean	Required	Boolean indicating whether the row was selected (true) or deselected (false)
`selectedRows` Set<string>	Required	Set containing the IDs of all currently selected rows

CellChangeProps

Property	Required	Description

`accessor` Accessor	Required	The column accessor/key that was edited
`newValue` CellValue	Required	The new value after editing
`row` Row	Required	The complete row object that was edited

ValueFormatterProps

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

ValueGetterProps

Property	Required	Description

`accessor` Accessor	Required	The column accessor/key for which the value is being extracted
`row` Row	Required	The complete row object to extract the value from
`rowIndex` number	Required	The row index (0-based)

ComparatorProps

Property	Required	Description

`rowA` Row	Required	The first row object to compare
`rowB` Row	Required	The second row object to compare
`valueA` CellValue	Required	The raw cell value from rowA for the current column being sorted
`valueB` CellValue	Required	The raw cell value from rowB for the current column being sorted
`direction` "ascending" \| "descending"	Required	The sort direction
`formattedValue` string \| number \| string[] \| number[] \| undefined	Optional	The formatted cell value (output from valueFormatter if defined). Available for both rowA and rowB. Useful when you need to compare formatted values or access both raw and formatted data in your comparison logic.

CellRendererProps

Property	Required	Description

`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
`theme` Theme	Required	Current theme of the table
`value` CellValue	Required	The raw cell value
`formattedValue` 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.

ExportValueProps

Property	Required	Description

`accessor` Accessor	Required	The column accessor/key for the cell being exported
`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
`formattedValue` string \| number \| undefined	Optional	The formatted cell value (if valueFormatter is defined)

CellClickProps

Property	Required	Description

`accessor` Accessor	Required	The column accessor/key of the clicked cell
`colIndex` number	Required	The column index of the clicked cell (0-based)
`row` Row	Required	The complete row object containing the clicked cell
`rowId` RowId	Required	The unique identifier of the row containing the clicked cell
`rowIndex` number	Required	The row index of the clicked cell (0-based)
`value` CellValue	Required	The value of the clicked cell

OnRowGroupExpandProps

Property	Required	Description

`row` Row	Required	The complete row object that is being expanded or collapsed
`depth` number	Required	The depth level of the row in the hierarchy (0 = top level, 1 = first nested level, etc.)
`event` MouseEvent	Required	The original mouse click event that triggered the expand/collapse action
`rowId` string \| number	Required	The unique identifier for the row (from rowIdAccessor)
`groupingKey` string	Optional	The property name that contains the children rows for this grouping level. Corresponds to the current level in the rowGrouping array.
`isExpanded` boolean	Required	Boolean indicating whether the row is being expanded (true) or collapsed (false). Use this to determine whether to fetch data.
`rowIndexPath` (string \| number)[]	Required	Array path through the nested data structure to reach this row. Each element is either a number (array index) or string (property name). Use this to directly navigate and update nested data without complex traversal logic.
`groupingKeys` string[]	Required	Array of all grouping keys from the hierarchy (from the rowGrouping prop). Provides context about the complete hierarchy structure.
`setLoading` (loading: boolean) => void	Required	Helper function to set the loading state for this specific row. When true, displays the loadingStateRenderer component. Call with false to clear the loading state.
`setError` (error: string \| null) => void	Required	Helper function to set an error state for this specific row. Pass an error message string to display the errorStateRenderer component, or null to clear the error state.
`setEmpty` (isEmpty: boolean, message?: string) => void	Required	Helper function to set an empty state for this specific row. When true, displays the emptyStateRenderer component. Optionally provide a custom message as the second parameter.

FilterCondition

Property	Required	Description

`accessor` Accessor	Required	The column accessor/key being filtered
`operator` FilterOperator	Required	The filter operation to perform
`value` CellValue	Optional	Single value for most filter operations
`values` CellValue[]	Optional	Array of values for 'between', 'in', etc. operations

Union Type Definitions

Property	Required	Description

`Accessor` keyof Row \| string	Optional	Valid property key that exists in the Row type. Used to safely access row data. Supports nested properties using dot notation (v1.7.6+) and array indices (v1.9.4+).
`CellValue` string \| number \| boolean \| undefined \| null \| string[] \| number[] \| Record<string, any>[]	Optional	Valid data types that can be stored in a table cell.
`Theme` "light" \| "dark" \| "sky" \| "violet" \| "neutral" \| "custom"	Optional	Built-in theme options for styling the table.
`AggregationType` "sum" \| "average" \| "count" \| "min" \| "max" \| "custom"	Optional	Available aggregation functions for grouped data.
`Pinned` "left" \| "right"	Optional	Column pinning position options.
`ChartOptions` object	Optional	Configuration object for customizing chart column appearance and behavior. Use with lineAreaChart and barChart column types.
`ColumnEditorPosition` "left" \| "right"	Optional	Position options for the column editor panel.
`Row` Record<string, CellValue \| Row[] \| Record<string, any>>	Optional	Data object representing a single table row. Can contain cell values, nested row arrays for hierarchical data, or any additional properties.
`HeaderObject.type` string \| number \| boolean \| date \| enum \| lineAreaChart \| barChart \| other	Optional	Data type for proper formatting and sorting behavior. Includes chart types for visualizing array data inline.

SortConfig

Property	Required	Description

`key` HeaderObject	Required	The HeaderObject representing the column being sorted.
`direction` "ascending" \| "descending"	Required	The sort direction for the column.

TableFilterState

Property	Required	Description	Example

`filterCondition` FilterCondition	Required	The FilterCondition object containing the filter logic.

TableRefType Methods

Property	Required	Description

`exportToCSV` (props?: ExportToCSVProps) => void	Optional	Exports the current table data to a CSV file. Respects active filters and sorting. Optionally accepts a props object to customize the filename.
`updateData` (params: { accessor: Accessor; rowIndex: number; newValue: CellValue }) => void	Optional	Programmatically update a specific cell value in the table. Useful for live updates and real-time data changes. Triggers cellUpdateFlash animation if enabled.
`setHeaderRename` (params: { accessor: Accessor; newLabel: string }) => void	Optional	Programmatically rename a column header. Useful for dynamic table configurations and internationalization.
`getVisibleRows` () => TableRow[]	Optional	Returns the currently visible rows in the table. When pagination is enabled, this returns only the rows on the current page. When filters are applied, returns only filtered rows. This is useful for getting a snapshot of what the user is currently viewing.
`getAllRows` () => TableRow[]	Optional	Returns all rows in the table as TableRow objects, flattened and including nested/grouped rows. Each TableRow contains the raw row data plus metadata like depth, position, and rowPath. Unlike getVisibleRows, this returns the complete dataset regardless of pagination, filters, or grouping state. Perfect for exporting complete data, analytics, or batch operations.
`getHeaders` () => HeaderObject[]	Optional	Returns the table's current header/column definitions. Includes all column configuration such as accessors, labels, types, and formatting options. Useful for dynamic table manipulation, export configurations, or building custom UI controls.

ExportToCSVProps

Property	Required	Description	Example

`filename` string	Optional	Custom filename for the exported CSV file. Defaults to 'table-export.csv' if not provided.

FooterRendererProps

Property	Required	Description

`currentPage` number	Required	The current page number (1-based index).
`startRow` number	Required	The starting row number for the current page (1-based index).
`endRow` number	Required	The ending row number for the current page (1-based index).
`totalRows` number	Required	The total number of rows in the table.
`totalPages` number	Required	The total number of pages based on rowsPerPage.
`rowsPerPage` number	Required	The number of rows displayed per page.
`hasPrevPage` boolean	Required	Boolean indicating if there is a previous page available.
`hasNextPage` boolean	Required	Boolean indicating if there is a next page available.
`onPrevPage` () => void	Required	Function to navigate to the previous page.
`onNextPage` () => Promise<void>	Required	Async function to navigate to the next page.
`onPageChange` (page: number) => void	Required	Function to navigate to a specific page number.
`prevIcon` ReactNode	Optional	Optional custom icon for the previous page button.
`nextIcon` ReactNode	Optional	Optional custom icon for the next page button.