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.
`height` string \| number	Optional	Height of the table container. If both height and maxHeight are defined, height will be ignored.
`maxHeight` string \| number	Optional	Maximum height of the table container with adaptive behavior. Works the same as height except that it will shrink if there are fewer rows. Enables virtualization while allowing the table to be smaller when content doesn't fill the maximum height. If both height and maxHeight are defined, height will be ignored.
`customTheme` CustomTheme	Optional	Custom theme configuration for dimensions and spacing. Only specify the properties you want to customize - all properties are optional and will use default values if not provided.
`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` "asc" \| "desc"	Optional	Sets the sort direction for the initial sort. Defaults to 'asc' if not specified. Only applies when initialSortColumn is also set.
`hideHeader` boolean	Optional	Flag for hiding the table header row. When true, the entire header row will be hidden while maintaining all table functionality including sorting, filtering, and column operations.
`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.
`onColumnVisibilityChange` (visibilityState: ColumnVisibilityState) => void	Optional	Callback triggered when column visibility changes (when users show/hide columns through the column editor). Receives a ColumnVisibilityState object mapping each column accessor to its visibility state (true = visible, false = hidden). Perfect for persisting user preferences or syncing visibility state with external storage.
`autoExpandColumns` boolean	Optional	When true, automatically scales all column widths proportionally to fill the entire table container width. The width property of each column is used as the base for proportional scaling. Note: minWidth is NOT enforced during scaling (columns can shrink below minWidth), and maxWidth is NOT checked at all. Recommended: Set to false on mobile devices (< 768px) as horizontal scrolling provides better UX than cramped columns on small screens.
`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.
`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 ChartOptions section for all available properties.
`minWidth` number \| string	Optional	Minimum width constraint for the column. Note: When autoExpandColumns is enabled, minWidth is NOT enforced during initial scaling - columns can be scaled below their minWidth.
`maxWidth` number \| string	Optional	Maximum width constraint for the column. Note: When autoExpandColumns is enabled, maxWidth is NOT enforced at all - the property is ignored during proportional scaling.
`isSortable` boolean	Optional	Enable sorting for this column.
`sortingOrder` Array<'asc' \| 'desc' \| null>	Optional	Custom sort order cycle for this column. Defines the sequence of sort states when clicking the column header. Default is ['asc', 'desc', null] which cycles through ascending → descending → no sort. Customize per column based on data type - use ['desc', 'asc', null] for numbers/dates where descending is more common, or ['asc', 'desc'] to prevent removing sort.
`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.
`nestedTable` NestedTableConfig	Optional	Configuration for nested tables that allows each level of row grouping to have its own independent grid structure with different columns and settings. When a row is expanded, its child data is displayed in a completely separate table with its own headers, column configuration, and features. This is different from standard row grouping where all levels share the same columns.
`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, rowIndex, rowPath, theme, value, formattedValue }: CellRendererProps) => ReactNode \| string	Optional	Custom render function for cell content. Receives both raw and formatted values, row path for nested data access, and other cell context 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 and from the column visibility drawer/popout menu. The column data is still available for CSV export. Useful for ID columns or metadata that should be exported but not displayed or toggled by users.
`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.

CustomTheme Configuration

Custom theme configuration for dimensions and spacing that affect virtualization calculations. All properties are optional and will use default values if not specified. For a comprehensive guide with examples and use cases, see the Custom Theme documentation.

CustomTheme Properties

Property	Required	Description

`rowHeight` number	Optional	Height of table rows in pixels. This value is used for virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 40px.
`headerHeight` number	Optional	Height of the table header in pixels. This value is used for virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 40px.
`footerHeight` number	Optional	Height of the table footer in pixels. This value is used for virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 50px.
`rowSeparatorWidth` number	Optional	Width of separators between rows in pixels. This value affects virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 1px.
`borderWidth` number	Optional	General border width in pixels (e.g., table borders, header borders). This value affects layout calculations and cannot be styled through CSS. If not specified, uses the default value of 1px.
`pinnedBorderWidth` number	Optional	Width of borders for pinned columns in pixels. This value affects layout calculations for pinned columns and cannot be styled through CSS. If not specified, uses the default value of 2px.
`nestedGridBorderWidth` number	Optional	Border width for nested grid tables (top + bottom) in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 2px.
`nestedGridPaddingTop` number	Optional	Top padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 8px.
`nestedGridPaddingBottom` number	Optional	Bottom padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 8px.
`nestedGridPaddingLeft` number	Optional	Left padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 16px.
`nestedGridPaddingRight` number	Optional	Right padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 16px.
`nestedGridMaxHeight` number	Optional	Maximum height for nested grids in pixels. This value controls how tall nested tables can grow before scrolling. If not specified, nested grids will grow to fit their content.
`selectionColumnWidth` number	Optional	Width of the row selection checkbox column in pixels. This value affects layout calculations and cannot be styled through CSS. If not specified, uses the default value of 40px.

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')

ChartOptions

Property	Required	Description

`min` number	Optional	Custom minimum value for chart scaling. If not provided, the minimum data value is used.
`max` number	Optional	Custom maximum value for chart scaling. If not provided, the maximum data value is used.
`width` number	Optional	Custom chart width in pixels. Default is 100.
`height` number	Optional	Custom chart height in pixels. Default is 30.
`color` string	Optional	Custom chart color (CSS color value). Overrides the theme color.
`fillColor` string	Optional	Custom fill color for area charts (CSS color value). Only applies to lineAreaChart type. Overrides the theme fill color.
`fillOpacity` number	Optional	Fill opacity for area charts. Value between 0 and 1. Default is 0.2. Only applies to lineAreaChart type.
`strokeWidth` number	Optional	Line stroke width in pixels. Default is 2. Only applies to lineAreaChart type.
`gap` number	Optional	Gap between bars in pixels. Default is 2. Only applies to barChart type.

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` "asc" \| "desc"	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
`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.

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

HeaderRendererProps

Property	Required	Description

`accessor` Accessor	Required	The column accessor/key identifying which column this header belongs to
`colIndex` number	Required	The zero-based index of the column within the table
`header` HeaderObject	Required	The complete HeaderObject containing all configuration for this column including label, width, and other properties
`components` HeaderRendererComponents	Optional	Object containing pre-rendered header components (sortIcon, filterIcon, collapseIcon, labelContent) that can be positioned anywhere in your custom header renderer. This gives you complete control over the layout and order of header elements.

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.
`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.
`SortDirection` "asc" \| "desc"	Optional	The sort direction for table columns. Used with applySortState() method for programmatic sort control. If direction is omitted from applySortState(), the sort cycles through: asc → desc → removed.
`SortColumn` { key: HeaderObject; direction: SortDirection }	Optional	Object representing the current sort state of the table. Contains the column being sorted (as a HeaderObject) and the sort direction. Returned by getSortState() method.

SortConfig

Property	Required	Description

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

TableFilterState

Property	Required	Description	Example

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

ColumnVisibilityState

Property	Required	Description	Example

`[accessor: string]` boolean	Required	Maps column accessor to visibility state. Each key is a column accessor, and the value is a boolean indicating whether the column is visible (true) or hidden (false).

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 }) => void	Optional	Programmatically triggers the header rename mode for a specific column. Sets the header cell to editing mode, allowing the user to rename it. The header must have enableHeaderRename enabled.
`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.
`getSortState` () => SortColumn \| null	Optional	Returns the current sort state of the table. Returns null if no sorting is applied, or a SortColumn object containing the sorted column and direction. Useful for persisting table state, synchronizing with external state management, or implementing custom sort UI.
`applySortState` (props?: { accessor: Accessor; direction?: SortDirection }) => Promise<void>	Optional	Programmatically applies a sort state to the table. Pass a column accessor and optional direction to sort, or undefined to clear sorting. If direction is omitted, the sort cycles through: asc → desc → removed. This method is async and returns a Promise. Perfect for implementing custom sort controls or coordinating sorting with external data sources.
`getFilterState` () => TableFilterState	Optional	Returns the current filter state of the table as a TableFilterState object. The object contains all active filters keyed by unique filter IDs. Each filter includes the column accessor, operator, and values. Useful for debugging, persisting filter state, or building custom filter UI.
`applyFilter` (filter: FilterCondition) => Promise<void>	Optional	Programmatically applies a filter to a specific column. Accepts a FilterCondition object specifying the column accessor, filter operator, and value(s). This method is async and returns a Promise. Supports all filter operators including equals, contains, greaterThan, between, and more. Perfect for implementing custom filter UI, applying saved filters, or creating filter presets.
`clearFilter` (accessor: Accessor) => Promise<void>	Optional	Clears the filter for a specific column identified by its accessor. This method is async and returns a Promise. Only removes filters applied to the specified column, leaving other column filters intact. Useful for implementing 'clear filter' buttons on individual columns or resetting specific filters programmatically.
`clearAllFilters` () => Promise<void>	Optional	Clears all active filters from the table at once. This method is async and returns a Promise. Resets the table to show all data without any filtering applied. Perfect for 'reset all filters' buttons or starting fresh with filter state.
`getCurrentPage` () => number	Optional	Returns the current page number when pagination is enabled. Page numbers are 1-indexed (first page is 1, not 0). Returns the current page regardless of whether pagination is client-side or server-side. Useful for tracking user navigation, syncing with URL parameters, or building custom pagination UI.
`setPage` (page: number) => Promise<void>	Optional	Programmatically navigates to a specific page when pagination is enabled. Accepts a 1-indexed page number (first page is 1). This method is async and returns a Promise. Works with both client-side and server-side pagination. If the page number is out of range, it will be clamped to valid bounds. Triggers the onPageChange callback when the page changes. Perfect for implementing custom pagination controls, deep linking, or restoring saved pagination state.
`expandAll` () => void	Optional	Expands all rows at all depths in the table. When working with hierarchical/grouped data, this will expand every level of the hierarchy, revealing all nested rows. Useful for 'expand all' buttons or when you want to show the complete data structure to users.
`collapseAll` () => void	Optional	Collapses all rows at all depths in the table. When working with hierarchical/grouped data, this will collapse every level of the hierarchy, hiding all nested rows. Perfect for 'collapse all' buttons or resetting the table to a compact view.
`expandDepth` (depth: number) => void	Optional	Expands all rows at a specific depth level (0-indexed). Depth 0 represents the top-level rows, depth 1 is the first nested level, depth 2 is the second nested level, and so on. This allows granular control over which hierarchy levels are visible. Useful for showing specific levels of detail without expanding everything.
`collapseDepth` (depth: number) => void	Optional	Collapses all rows at a specific depth level (0-indexed). Depth 0 represents the top-level rows, depth 1 is the first nested level, and so on. This allows you to selectively hide specific hierarchy levels while keeping others visible. Useful for managing complex hierarchies and controlling information density.
`toggleDepth` (depth: number) => void	Optional	Toggles the expansion state for all rows at a specific depth level (0-indexed). If the depth is currently expanded, it will be collapsed, and vice versa. This provides a convenient way to toggle visibility of an entire hierarchy level without tracking state manually.
`setExpandedDepths` (depths: Set<number>) => void	Optional	Sets which depth levels should be expanded, replacing the current expansion state entirely. Accepts a Set of depth numbers (0-indexed). This is useful for restoring saved expansion state, implementing presets, or coordinating expansion across multiple tables. Any depth not in the Set will be collapsed.
`getExpandedDepths` () => Set<number>	Optional	Returns a Set containing all currently expanded depth levels (0-indexed). This allows you to inspect which hierarchy levels are currently visible. Useful for saving expansion state, building custom UI controls, or coordinating with other components.
`getGroupingProperty` (depth: number) => Accessor \| undefined	Optional	Returns the grouping property name (accessor) for a specific depth index (0-indexed). This maps depth levels to their corresponding property names in your rowGrouping configuration. Returns undefined if the depth doesn't exist. Useful for understanding the hierarchy structure or building dynamic UI that adapts to the grouping configuration.
`getGroupingDepth` (property: Accessor) => number	Optional	Returns the depth index (0-indexed) for a specific grouping property name (accessor). This is the inverse of getGroupingProperty - it maps property names to their depth levels in the hierarchy. Returns -1 if the property is not part of the grouping configuration. Useful for programmatically determining which level a property belongs to.

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.