Table·hook·@astryxdesign/core

useTableSelection

Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.

Open in Playground @astryxdesign/core/Table

Signature

Call shape

useTableSelection()

Showcases and examples

3 documented examples

Table: Bulk Actions

Controlled row selection with the reusable TableSelectionToolbar rendered in flow above the table. Product actions occupy the logical start; synchronized selection count and complete clear action occupy the logical end.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · table-bulk-actions-table

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {Button} from '@astryxdesign/core/Button';
import {
  Table,
  TableSelectionToolbar,
  useTableSelection,
  useTableSelectionState,
  proportional,
} from '@astryxdesign/core/Table';
import type {TableColumn} from '@astryxdesign/core/Table';

interface User extends Record<string, unknown> {
  id: string;
  name: string;
  email: string;
  role: string;
}

const users: User[] = [
  {id: '1', name: 'Alice', email: 'alice@example.com', role: 'Engineer'},
  {id: '2', name: 'Bob', email: 'bob@example.com', role: 'Designer'},
  {id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'Manager'},
  {id: '4', name: 'Diana', email: 'diana@example.com', role: 'Engineer'},
  {id: '5', name: 'Eve', email: 'eve@example.com', role: 'Admin'},
];

const columns: TableColumn<User>[] = [
  {key: 'name', header: 'Name', width: proportional(1)},
  {key: 'email', header: 'Email', width: proportional(2)},
  {key: 'role', header: 'Role', width: proportional(1)},
];

export default function TableBulkActionsTable() {
  const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());

  const {selectionConfig, selectionState} = useTableSelectionState<User>({
    data: users,
    idKey: 'id',
    selectedKeys,
    setSelectedKeys,
  });
  const selectionPlugin = useTableSelection<User>(selectionConfig);

  return (
    <div>
      <TableSelectionToolbar
        selection={selectionState}
        startContent={
          <>
            <Button label="Export" variant="ghost" onClick={() => {}} />
            <Button
              label="Delete"
              variant="ghost"
              onClick={selectionState.clearSelection}
            />
          </>
        }
      />
      <Table
        data={users}
        columns={columns}
        idKey="id"
        plugins={{selection: selectionPlugin}}
      />
    </div>
  );
}

Usage

Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.

Typed props

Prop	Type and behavior
`getIsItemSelected`	`(item: T) => boolean` · required Returns whether the given item is currently selected.
`onSelectItem`	`(event: {item: T; isSelected: boolean}) => void` · required Called when a row checkbox is toggled. isSelected is the new desired state.
`onSelectAll`	`(event: {isAllSelected: boolean}) => void` · required Called when the select-all header checkbox is toggled.
`getIsAllSelected`	`() => boolean` · required Returns whether all selectable items are currently selected.
`getIsIndeterminate`	`() => boolean` Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.
`getIsItemSelectable`	`(item: T) => boolean` · default () => true Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.
`getIsItemEnabled`	`(item: T) => boolean` · default () => true Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.
`getRowLabel`	`(item: T) => string` Derives a human-readable identity for a row; the row checkbox's hidden label becomes `Select ${getRowLabel(item)}` so screen readers announce which row each checkbox selects. Falls back to "Select row" when omitted.
`hasRowHighlight`	`boolean` · default true Paints checked rows with the accent wash. Set false when the surrounding UI already uses row background to mean something else (a row open in a detail panel, say). The wash is an inline style, so it cannot be overridden from userland. Only the background is dropped: aria-selected is still set on checked rows either way.