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.
`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.
`rowsPerPage` number	Optional	Number of rows per page for pagination.
`selectableCells` boolean	Optional	Enable cell selection functionality.
`selectableColumns` boolean	Optional	Flag for selectable column headers.
`shouldPaginate` boolean	Optional	Flag for enabling pagination.
`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.
`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.

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.
`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. Options: string number boolean date enum other
`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 }: { accessor: Accessor; colIndex: number; row: Row; theme: Theme; }) => ReactNode \| string	Optional	Custom render function for cell content.
`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.

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

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

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	Optional	Valid property key that exists in the Row type. Used to safely access row data.
`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" \| "frost" \| "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.
`ColumnEditorPosition` "left" \| "right"	Optional	Position options for the column editor panel.
`Row` Record<string, CellValue \| Row[]>	Optional	Data object representing a single table row. Can contain cell values or nested row arrays for hierarchical data.
`HeaderObject.type` string \| number \| boolean \| date \| enum \| other	Optional	Data type for proper formatting and sorting behavior.

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.

ExportToCSVProps

Property	Required	Description	Example

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