Components / More

SortButton

The button in a sortable column's header: the header text and an icon that shows the sort. Table and DataGrid render it for their sortable columns.

Source Edit this page

Default

When to use

Use Table or DataGrid and mark columns sortable: they render SortButton for you. Reach for it directly only in a table of your own, inside a header cell that carries aria-sort.

Use something else when the control sorts a whole list from outside it (a Select of sort orders) or toggles an option (Button with pressed).

Usage

tsx

import { SortButton } from "@arshad-shah/cynosure";

<th aria-sort={sort?.key === "name" ? sort.direction : "none"}>
  <SortButton direction={sort?.key === "name" ? sort.direction : undefined} onClick={() => cycleSort("name")}>
    Name
  </SortButton>
</th>

fill makes it fill a fixed-height header cell, as in DataGrid; align="end" puts the icon before the label for numeric columns.

Fills its cell

Props

Every prop of SortButton
Prop	What it does	Type
`children`	The column's header text. It is cut short with an ellipsis when the column is too narrow.	`ReactNode`
`direction`	How the column is sorted now; nothing when it is not. The icon follows it.	`SortDirection`
`onClick`	Pressed: change the sort (Table and DataGrid cycle ascending, descending, unsorted with `nextSort`).	`(() => void)`
`fill`	Fill the header cell (a data grid's fixed-height header); otherwise the button is as wide as its label.	`boolean`
`align`	`end` (a numeric column) puts the icon before the label, so the label lines up with the values.	`"start" \| "end"`
`tabIndex`	Tab order: a grid with one tab stop sets -1 on all but the active header.	`number`
`aria-keyshortcuts`	The shortcuts the header also answers to (a resizable column's Alt+arrows).	`string`
`data-cell`	A grid's cell coordinates, for its keyboard navigation.	`string`
`className`	Added to the root element, for layout.	`string`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Key	Does
Enter, Space	Press: change the sort

The icon follows direction: both ways when unsorted, an arrow up for ascending, down for descending. It is decorative: the header cell's aria-sort says how the column is sorted.
A sorted column's button is drawn in the ink colour; an unsorted one takes the header's colour.
A long header is cut short with an ellipsis rather than overflowing its column.
tabIndex, aria-keyshortcuts and data-cell reach the button, for a grid with one tab stop.

Touch

The hit area is at least 24px tall, and 44px on touch screens; a filling button takes its cell's height.

Theming

Tokens: --cy-sort-button-padding (inline padding when it fills its cell, default --cy-space-4). Colours come from the header around it.

Table, DataGrid.

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

TouchLink to "Touch"

ThemingLink to "Theming"