ColumnSettings
A button that opens a list of a table's columns to show, hide and reorder by dragging or with Alt and the arrow keys.
import { ColumnSettings } from "@butteryui/react";Demo
Order 路 Customer 路 Status 路 Placed
When to use it
Use it for
- A DataTable with more columns than everyone needs
- Letting people put a table's columns in their own order
Not for
- Filtering rows: use FilterBar
- Switching between saved setups: use SavedViews
Examples
Columns count
The columns alone: it keeps its own layout and reports each change, here as a count.
Showing 4 of 4 columns
Orders columns
Columns for an orders table, Placed hidden at first: hide some, drag the rest, and Reset hides Placed again.
Order 路 Customer 路 Status 路 Total
Table toolbar
A customers table with its toolbar: search on one side, and column settings the table's columns follow.
Variants and states
Show, hide and reorder
Drag a column by its grip, or press Alt and Up or Down on it; Reset puts them back.
Order 路 Customer 路 Status 路 Placed 路 Total
Props
ColumnSettings
| Prop | Type | Default | Description |
|---|---|---|---|
columnsrequired | readonly ColumnSetting[] | Every column, in its default order. The first always shows. | |
layout | ColumnLayout | Which columns show, and in what order. Pair with onLayoutChange to control it. | |
defaultLayout | ColumnLayout | The layout it starts with when uncontrolled, and the one Reset puts back. Defaults to every column, in order. | |
onLayoutChange | ((layout: ColumnLayout) => void) | Called with the new layout. | |
open | boolean | Whether the popover is open. Pair with onOpenChange to control it. | |
defaultOpen | boolean | false | Whether the popover starts open when uncontrolled. Defaults to false. |
onOpenChange | ((open: boolean) => void) | Called when the popover opens or closes. | |
labels | Partial<ColumnSettingsLabels> | Words to use instead of the English ones. |
It also takes Omit<ComponentPropsWithRef<"button">, "children">.
ColumnSetting
One column a `ColumnSettings` lists.
| Field | Type | Default | Description |
|---|---|---|---|
idrequired | string | The column's id, as the table knows it. | |
labelrequired | string | Its name. |
ColumnLayout
Which columns show, and in what order.
| Field | Type | Default | Description |
|---|---|---|---|
orderrequired | readonly string[] | Every column's id, in the order they show. | |
visiblerequired | ReadonlySet<string> | The ids of the columns that show. |
ColumnSettingsLabels
The words a `ColumnSettings` uses, for other languages.
| Field | Type | Default | Description |
|---|---|---|---|
buttonrequired | string | Names the icon button and its popover. | |
resetrequired | string | The button that puts the default columns back. | |
moverequired | (column: string) => string | Names a column's grip, from the column's name. |
Accessibility
An icon button named Columns opens a dialog popover. Each column has a checkbox named by it (the first is always on, disabled) and a grip button named Move and the column, which moves it with Alt and Up or Down (announced through aria-keyshortcuts) as well as by dragging.
| Keys | What they do |
|---|---|
| Enter or Space | Opens the list from the Columns button, or presses Reset |
| Tab or Shift+Tab | Moves between each column's grip and checkbox, then Reset |
| Space | Shows or hides the focused column; the first one always shows |
| Alt+ArrowUp or Alt+ArrowDown | Moves the focused column one place up or down |
| Escape | Closes the list and puts focus back on the Columns button |
Motion
It changes shape as one surface, on `spring.smooth`, or `spring.morph` for a big change, rather than closing and reopening.
With reduced motion: The list fades in and out in 100ms instead of growing from the button (inside AppShell layout="sidebar" it appears at once either way), and a moved column's neighbours take their new places at once instead of sliding.
Layout
The Columns button is a 36px icon button (--bt-h-button). Its popover is 240px wide, never wider than the room it has, with a row per column at least 28px tall (--bt-h-sm), 4 apart: a 24px grip and the column's checkbox, whose name wraps.
Related
See it in the roastery demo's orders.