Documentation

Column Sorting

Column sorting allows users to organize table data in ascending or descending order based on column values. This feature is essential for data analysis and quick information retrieval.

CodeSandbox

Basic Sorting

To enable sorting for a column, add the isSortable: true property to your column definition.

✨ New in v1.9.4: Array Index Support

Accessors now support nested array paths using bracket notation. This allows you to sort by specific array elements without writing custom logic.

awards[0] - Sort by first award
albums[0].title - Sort by first album's title
releaseDate[0] - Sort by first release date

Column Sorting Configuration

Property	Required	Description

`HeaderObject.isSortable` boolean	Optional	Enables sorting functionality for the column. When true, users can click the column header to sort data.
`HeaderObject.comparator` (props: ComparatorProps) => number	Optional	Custom sorting function based on row-level metadata or complex logic. Receives full row objects and sort direction, allowing you to sort by multiple fields, nested properties, or domain-specific rules.
`HeaderObject.valueGetter` (props: ValueGetterProps) => CellValue	Optional	Function to extract values from nested objects or compute values dynamically for sorting operations. Useful when the displayed value differs from the sorting value, or when sorting by deeply nested properties.

Advanced Sorting

For complex sorting scenarios, Simple Table provides two powerful options:

Custom Comparator

Use comparator when you need to sort based on multiple fields, row metadata, or custom business logic:

💡 Use Cases

Sort by multiple fields with priority (e.g., priority level + performance score)
Access metadata or related fields not directly in the column
Implement domain-specific sorting rules (e.g., custom status ordering)
Sort by computed values derived from multiple row properties

Value Getter

Use valueGetter to extract nested values or compute values for sorting, especially when displaying formatted text:

💡 Use Cases

Sort by nested/computed values while displaying formatted text
Access deeply nested properties (e.g., row.metadata.seniorityLevel)
Calculate derived values for sorting operations
Combine with valueFormatter to separate sorting logic from display

🎯 Comparator vs ValueGetter

Use comparator when you need full control over the sorting logic with access to both rows. Use valueGetter when you want the default sorting behavior but need to extract or compute the value first.

Initial Sort State

Set the table to load with a default sort applied using initialSortColumn and initialSortDirection. This is perfect for showing users the most relevant data first, like sorting by date (newest first) or revenue (highest first).

💡 Use Cases

Sort by date to show newest records first
Sort by revenue/sales to highlight top performers
Sort by priority or status to show critical items first
Provide a consistent, predictable initial view for users

React TSX

Copy

1<SimpleTable
2  defaultHeaders={headers}
3  rows={data}
4  initialSortColumn="revenue"        // Sort by revenue column
5  initialSortDirection="desc"  // Show highest revenue first
6  // ... other props
7/>

The table will load with the sort applied, and users can still change the sort by clicking column headers.

External Sorting

For advanced use cases, you can handle sorting externally - perfect for server-side sorting, API integration, or custom sorting logic. This demo shows how to manage sorting completely outside the table component.

External Sort Status: No sorting applied

CodeSandbox

External sorting provides two key benefits:

API Integration: Use onSortChange to trigger server-side sorting while keeping the table's UI sorting indicators.
Complete Control: Use externalSortHandling= to disable all internal sorting and provide your own pre-sorted data.

External Sorting Configuration

Property	Required	Description

`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. Supports simple accessors, nested paths (dot notation), and array indices (v1.9.4+).
`initialSortDirection` "asc" \| "desc"	Optional	Sets the sort direction for the initial sort. Defaults to 'asc' if not specified.
`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.
`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.