bo-grid v3.1.0

Columns

.md

Moving & hiding

Let users drag columns into a new order and hide or show them from a column menu or a Columns panel, or drive visibility from your own UI.

Users can drag a column header to move the column, and hide or show columns from a per-column menu or a Columns panel. Your app can also hide columns itself through hiddenColumns, and the grid reports every change so you can save it.

Drag a header sideways to move its column. Open a header’s ⋮ menu to sort, pin, autosize or hide it, and use the Columns button to bring hidden columns back:

column-moving.svelte GitHub ↗

Moving columns

Drag any column header to a new position. onColumnReorder receives the new order of column keys, and persistKey remembers it across reloads (in localStorage):

<Grid {rows} {columns} persistKey="watchlist" onColumnReorder={(keys) => (columnOrder = keys)} height={480} />

The columns array you pass keeps its own order; the user’s order is layered on top. api.getState() and api.applyState() capture and restore it along with widths, pins, sorts and filters (see Grid API).

The column menu

columnMenu adds a ⋮ button to each header, also opened with Alt+↓ on the focused column. It offers:

  • Sort ascending or descending.
  • Pin left or right, or unpin (see Pinned columns).
  • Autosize: fit the column to its content.
  • Hide column.
  • Filter, when the grid also has filterMenu (see Sorting & filtering).

The Columns panel

columnsPanel adds a Columns button that opens a checklist of every column, to hide and show them. It is the place to bring back a column hidden from the menu.

<Grid {rows} {columns} columnMenu columnsPanel height={480} />

Hiding columns from your app

hiddenColumns takes the keys of columns to hide. It is controlled: build your own column picker and drive the prop. Columns the user hides at runtime are added to it, and onColumnVisibilityChange reports the full set of hidden keys whenever it changes:

<script lang="ts">
  let hidden = $state(['bonus', 'rating']);
</script>

<Grid {rows} {columns} hiddenColumns={hidden} columnMenu onColumnVisibilityChange={(keys) => (hidden = keys)} height={480} />

Runtime hides and pins are remembered under persistKey too.

Reference

Grid props from the types
onColumnReorder (keys: string[]) => void

Called with the new column-key order after a header drag-reorder.

Example 
<Grid {rows} {columns} height={480} onColumnReorder={(keys) => save('order', keys)} />
columnMenu boolean Default false

Enable a per-column header menu (a ⋮ trigger) with sort, hide and (with filterMenu) filter actions.

columnsPanel boolean Default false

Show a "Columns" button that opens a panel to toggle column visibility (the place to restore columns hidden via the menu). Lazy-loaded.

hiddenColumns string[] Default []

Column keys to hide (controlled). Build your own column-picker UI and drive this prop — the grid stays presentation-only. Composed (union) with columns the user hides at runtime via the column menu.

Example 
<Grid {rows} {columns} height={480} hiddenColumns={showVolume ? [] : ['vol']} />
onColumnVisibilityChange (hidden: string[]) => void

Called with all currently-hidden column keys whenever the runtime set changes (column menu hide/show).

Example 
<Grid {rows} {columns} height={480} columnMenu onColumnVisibilityChange={(hidden) => save('hidden', hidden)} />
persistKey string Default undefined

Remember the user's layout (column order, widths, hidden and pinned columns, pinned rows) in localStorage under this key.

Grid API from the types
getState (): GridState

Snapshot of the user's layout: order, widths, hidden, pins, sorts, filters. A plain object, safe to JSON.stringify and store.

Example 
localStorage.setItem('orders-layout', JSON.stringify(api.getState()));
applyState (state: unknown): boolean

Restore a snapshot, reconciled against the columns as they are now. Returns false when the state is unusable (foreign version, not an object).

Example 
const saved = localStorage.getItem('orders-layout');
if (saved) api.applyState(JSON.parse(saved));