Sorting APIs

State

Sorting state is stored on the table using the following shape:

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:

This is the type signature for every sorting function:

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:

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

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

sortDescFirst?: boolean

sortDescFirst?: boolean

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

enableSorting

enableSorting?: boolean

enableSorting?: boolean

Enables/Disables sorting for this column.

enableMultiSort

enableMultiSort?: boolean

enableMultiSort?: boolean

Enables/Disables multi-sorting for this column.

invertSorting

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

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

getAutoSortingFn: () => SortingFn<TData>

getAutoSortingFn: () => SortingFn<TData>

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

getAutoSortDir

getAutoSortDir: () => SortDirection

getAutoSortDir: () => SortDirection

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

getSortingFn

getSortingFn: () => SortingFn<TData>

getSortingFn: () => SortingFn<TData>

Returns the resolved sorting function to be used for this column

getNextSortingOrder

getNextSortingOrder: () => SortDirection | false

getNextSortingOrder: () => SortDirection | false

Returns the next sorting order.

getCanSort

getCanSort: () => boolean

getCanSort: () => boolean

Returns whether this column can be sorted.

getCanMultiSort

getCanMultiSort: () => boolean

getCanMultiSort: () => boolean

Returns whether this column can be multi-sorted.

getSortIndex

getSortIndex: () => number

getSortIndex: () => number

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

getIsSorted

getIsSorted: () => false | SortDirection

getIsSorted: () => false | SortDirection

Returns whether this column is sorted.

getFirstSortDir

getFirstSortDir: () => SortDirection

getFirstSortDir: () => SortDirection

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

clearSorting

clearSorting: () => void

clearSorting: () => void

Removes this column from the table's sorting state

toggleSorting

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

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

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:

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

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

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

enableSorting?: boolean

enableSorting?: boolean

Enables/Disables sorting for the table.

enableSortingRemoval

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

enableMultiRemove?: boolean

enableMultiRemove?: boolean

Enables/disables the ability to remove multi-sorts

enableMultiSort

enableMultiSort?: boolean

enableMultiSort?: boolean

Enables/Disables multi-sorting for the table.

sortDescFirst

sortDescFirst?: boolean

sortDescFirst?: boolean

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

getSortedRowModel

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

maxMultiSortColCount?: number

maxMultiSortColCount?: number

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

isMultiSortEvent

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

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

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

Sets or updates the state.sorting state.

resetSorting

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

getPreSortedRowModel: () => RowModel<TData>

getPreSortedRowModel: () => RowModel<TData>

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

getSortedRowModel

getSortedRowModel: () => RowModel<TData>

getSortedRowModel: () => RowModel<TData>

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