📄 tanstack/table/v8/docs/api/features/sorting

export type SortDirection = 'asc' | 'desc'

export type ColumnSort = {
  id: string
  desc: boolean
}

export type SortingState = ColumnSort[]

export type SortingTableState = {
  sorting: SortingState
}


export type SortDirection = 'asc' | 'desc'

export type ColumnSort = {
  id: string
  desc: boolean
}

export type SortingState = ColumnSort[]

export type SortingTableState = {
  sorting: SortingState
}

Sorting Functions
-----------------

The following sorting functions are built-in to the table core:

alphanumeric
- Sorts by mixed alphanumeric values without case-sensitivity. Slower, but more accurate if your strings contain numbers that need to be naturally sorted.
alphanumericCaseSensitive
- Sorts by mixed alphanumeric values with case-sensitivity. Slower, but more accurate if your strings contain numbers that need to be naturally sorted.
text
- Sorts by text/string values without case-sensitivity. Faster, but less accurate if your strings contain numbers that need to be naturally sorted.
textCaseSensitive
- Sorts by text/string values with case-sensitivity. Faster, but less accurate if your strings contain numbers that need to be naturally sorted.
datetime
- Sorts by time, use this if your values are Date objects.
basic
- Sorts using a basic/standard a > b ? 1 : a < b ? -1 : 0 comparison. This is the fastest sorting function, but may not be the most accurate.

Every sorting function receives 2 rows and a column ID and are expected to compare the two rows using the column ID to return -1, 0, or 1 in ascending order. Here's a cheat sheet:

| Return | Ascending Order | | --- | --- | | -1 | a < b | | 0 | a === b | | 1 | a > b |

This is the type signature for every sorting function:

tsx

export type SortingFn<TData extends AnyData> = {
  (rowA: Row<TData>, rowB: Row<TData>, columnId: string): number
}


export type SortingFn<TData extends AnyData> = {
  (rowA: Row<TData>, rowB: Row<TData>, columnId: string): number
}

#### Using Sorting Functions

Sorting functions can be used/referenced/defined by passing the following to columnDefinition.sortingFn:

A string that references a built-in sorting function
A string that references a custom sorting functions provided via the tableOptions.sortingFns option
A function directly provided to the columnDefinition.sortingFn option

The final list of sorting functions available for the columnDef.sortingFn use the following type:

tsx

export type SortingFnOption<TData extends AnyData> =
  | 'auto'
  | SortingFns
  | BuiltInSortingFns
  | SortingFn<TData>


export type SortingFnOption<TData extends AnyData> =
  | 'auto'
  | SortingFns
  | BuiltInSortingFns
  | SortingFn<TData>

Column Def Options
------------------ ### sortingFn

tsx

sortingFn?: SortingFn | keyof SortingFns | keyof BuiltInSortingFns


sortingFn?: SortingFn | keyof SortingFns | keyof BuiltInSortingFns

The sorting function to use with this column.

Options:

A string referencing a built-in sorting function )
A custom sorting function

### sortDescFirst

tsx

sortDescFirst?: boolean


sortDescFirst?: boolean

Set to true for sorting toggles on this column to start in the descending direction.

### enableSorting

tsx

enableSorting?: boolean


enableSorting?: boolean

Enables/Disables sorting for this column.

### enableMultiSort

tsx

enableMultiSort?: boolean


enableMultiSort?: boolean

Enables/Disables multi-sorting for this column.

### invertSorting

tsx

invertSorting?: boolean


invertSorting?: boolean

Inverts the order of the sorting for this column. This is useful for values that have an inverted best/worst scale where lower numbers are better, eg. a ranking (1st, 2nd, 3rd) or golf-like scoring

### sortUndefined

tsx

sortUndefined?: 'first' | 'last' | false | -1 | 1 // defaults to 1


sortUndefined?: 'first' | 'last' | false | -1 | 1 // defaults to 1

'first'
- Undefined values will be pushed to the beginning of the list
'last'
- Undefined values will be pushed to the end of the list
false
- Undefined values will be considered tied and need to be sorted by the next column filter or original index (whichever applies)
-1
- Undefined values will be sorted with higher priority (ascending) (if ascending, undefined will appear on the beginning of the list)
1
- Undefined values will be sorted with lower priority (descending) (if ascending, undefined will appear on the end of the list)

NOTE: 'first' and 'last' options are new in v8.16.0

Column API
---------- ### getAutoSortingFn

tsx

getAutoSortingFn: () => SortingFn<TData>


getAutoSortingFn: () => SortingFn<TData>

Returns a sorting function automatically inferred based on the columns values.

### getAutoSortDir

tsx

getAutoSortDir: () => SortDirection


getAutoSortDir: () => SortDirection

Returns a sort direction automatically inferred based on the columns values.

### getSortingFn

tsx

getSortingFn: () => SortingFn<TData>


getSortingFn: () => SortingFn<TData>

Returns the resolved sorting function to be used for this column

### getNextSortingOrder

tsx

getNextSortingOrder: () => SortDirection | false


getNextSortingOrder: () => SortDirection | false

Returns the next sorting order.

### getCanSort

tsx

getCanSort: () => boolean


getCanSort: () => boolean

Returns whether this column can be sorted.

### getCanMultiSort

tsx

getCanMultiSort: () => boolean


getCanMultiSort: () => boolean

Returns whether this column can be multi-sorted.

### getSortIndex

tsx

getSortIndex: () => number


getSortIndex: () => number

Returns the index position of this column's sorting within the sorting state

### getIsSorted

tsx

getIsSorted: () => false | SortDirection


getIsSorted: () => false | SortDirection

Returns whether this column is sorted.

### getFirstSortDir

tsx

getFirstSortDir: () => SortDirection


getFirstSortDir: () => SortDirection

Returns the first direction that should be used when sorting this column.

### clearSorting

tsx

clearSorting: () => void


clearSorting: () => void

Removes this column from the table's sorting state

### toggleSorting

tsx

toggleSorting: (desc?: boolean, isMulti?: boolean) => void


toggleSorting: (desc?: boolean, isMulti?: boolean) => void

Toggles this columns sorting state. If desc is provided, it will force the sort direction to that value. If isMulti is provided, it will additivity multi-sort the column (or toggle it if it is already sorted).

### getToggleSortingHandler

tsx

getToggleSortingHandler: () => undefined | ((event: unknown) => void)


getToggleSortingHandler: () => undefined | ((event: unknown) => void)

Returns a function that can be used to toggle this column's sorting state. This is useful for attaching a click handler to the column header.

Table Options
------------- ### sortingFns

tsx

sortingFns?: Record<string, SortingFn>


sortingFns?: Record<string, SortingFn>

This option allows you to define custom sorting functions that can be referenced in a column's sortingFn option by their key. Example:

tsx

declare module '@tanstack/table-core' {
  interface SortingFns {
    myCustomSorting: SortingFn<unknown>
  }
}

const column = columnHelper.data('key', {
  sortingFn: 'myCustomSorting',
})

const table = useReactTable({
  columns: [column],
  sortingFns: {
    myCustomSorting: (rowA: any, rowB: any, columnId: any): number =>
      rowA.getValue(columnId).value < rowB.getValue(columnId).value ? 1 : -1,
  },
})


declare module '@tanstack/table-core' {
  interface SortingFns {
    myCustomSorting: SortingFn<unknown>
  }
}

const column = columnHelper.data('key', {
  sortingFn: 'myCustomSorting',
})

const table = useReactTable({
  columns: [column],
  sortingFns: {
    myCustomSorting: (rowA: any, rowB: any, columnId: any): number =>
      rowA.getValue(columnId).value < rowB.getValue(columnId).value ? 1 : -1,
  },
})

### manualSorting

tsx

manualSorting?: boolean


manualSorting?: boolean

Enables manual sorting for the table. If this is true, you will be expected to sort your data before it is passed to the table. This is useful if you are doing server-side sorting.

### onSortingChange

tsx

onSortingChange?: OnChangeFn<SortingState>


onSortingChange?: OnChangeFn<SortingState>

If provided, this function will be called with an updaterFn when state.sorting changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.

### enableSorting

tsx

enableSorting?: boolean


enableSorting?: boolean

Enables/Disables sorting for the table.

### enableSortingRemoval

tsx

enableSortingRemoval?: boolean


enableSortingRemoval?: boolean

Enables/Disables the ability to remove sorting for the table.

If true then changing sort order will circle like: 'none' -> 'desc' -> 'asc' -> 'none' -> ...
If false then changing sort order will circle like: 'none' -> 'desc' -> 'asc' -> 'desc' -> 'asc' -> ...

### enableMultiRemove

tsx

enableMultiRemove?: boolean


enableMultiRemove?: boolean

Enables/disables the ability to remove multi-sorts

### enableMultiSort

tsx

enableMultiSort?: boolean


enableMultiSort?: boolean

Enables/Disables multi-sorting for the table.

### sortDescFirst

tsx

sortDescFirst?: boolean


sortDescFirst?: boolean

If true, all sorts will default to descending as their first toggle state.

### getSortedRowModel

tsx

getSortedRowModel?: (table: Table<TData>) => () => RowModel<TData>


getSortedRowModel?: (table: Table<TData>) => () => RowModel<TData>

This function is used to retrieve the sorted row model. If using server-side sorting, this function is not required. To use client-side sorting, pass the exported getSortedRowModel() from your adapter to your table or implement your own.

### maxMultiSortColCount

tsx

maxMultiSortColCount?: number


maxMultiSortColCount?: number

Set a maximum number of columns that can be multi-sorted.

### isMultiSortEvent

tsx

isMultiSortEvent?: (e: unknown) => boolean


isMultiSortEvent?: (e: unknown) => boolean

Pass a custom function that will be used to determine if a multi-sort event should be triggered. It is passed the event from the sort toggle handler and should return true if the event should trigger a multi-sort.

Table API
--------- ### setSorting

tsx

setSorting: (updater: Updater<SortingState>) => void


setSorting: (updater: Updater<SortingState>) => void

Sets or updates the state.sorting state.

### resetSorting

tsx

resetSorting: (defaultState?: boolean) => void


resetSorting: (defaultState?: boolean) => void

Resets the sorting state to initialState.sorting, or true can be passed to force a default blank state reset to [].

### getPreSortedRowModel

tsx

getPreSortedRowModel: () => RowModel<TData>


getPreSortedRowModel: () => RowModel<TData>

Returns the row model for the table before any sorting has been applied.

### getSortedRowModel

tsx

getSortedRowModel: () => RowModel<TData>


getSortedRowModel: () => RowModel<TData>

Returns the row model for the table after sorting has been applied.

Edit on GitHub

Global Filtering

Grouping

Partners Become a Partner

scarf analytics