TableSelection

Server component with client leaf TableSelection

ImportCopy Anchor Link

import { TableSelectAll, TableSelectRow, TableSelection } from '@nizivo/react/table-selection';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/checkbox.css and @nizivo/react/css/table.css
import '@nizivo/react/css/table-selection.css';

Static or interactiveCopy Anchor Link

Server, with one client part. TableSelectAll and TableSelectRow render native checkboxes with Checkbox's look and no client JavaScript; TableSelection is one client island around the whole table. Import them from @nizivo/react/table-selection, next to Table from @nizivo/react/table: a page that does not use selection loads none of it, under Turbopack and webpack alike. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

Bulk actionsCopy Anchor Link

Put a TableSelectRow in each row and a TableSelectAll in the header, and wrap the table in TableSelection. Each row's box is a native checkbox that submits its value under name (ids by default) with its form, so a bulk action works before any JavaScript runs: pass form with the id of a form outside the table, as the example's "Archive selected" does. Give every row's box its own name (aria-label="Select order 1042"). A checked row paints bg/brand-subtle through CSS, with no script.

TableSelection adds what a native checkbox cannot do: the header's box checks or clears every row and shows the mixed state when only some are selected, Shift-click selects a range, and Escape clears the selection. A client owner hears every change through onSelectionChange(ids); a Server Component reads the selection from the submitted form. Rows with disabled boxes are left out.

The action barCopy Anchor Link

BulkActionBar is the bar over the table, with how many rows are selected and the actions; TableSelection writes its count.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Stack } from '@nizivo/react/stack';
import { Table } from '@nizivo/react/table';
import { BulkActionBar } from '@nizivo/react/bulk-action-bar';
import { TableSelectAll, TableSelection, TableSelectRow } from '@nizivo/react/table-selection';

const MONEY = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });

const PRODUCTS = [
  ['mug-014', 'Stoneware mug', '124 in stock', 28],
  ['apron-002', 'Linen apron', '8 in stock', 42],
  ['coaster-007', 'Ceramic coaster set', 'Sold out', 18.5],
  ['bowl-021', 'Speckled bowl', '36 in stock', 24],
] as const;

export function TableSelectionExample(): JSX.Element {
  return (
    <Stack gap="3">
      <TableSelection>
        <BulkActionBar defaultCount={1}>
          <form id="products-bulk" action="#">
            <Button type="submit" size="sm" variant="secondary">
              Archive selected
            </Button>
          </form>
        </BulkActionBar>
        <Table.Container>
          <Table.Root>
            <Table.Caption visuallyHidden>Products</Table.Caption>
            <Table.Header>
              <Table.Row>
                <Table.Head>
                  <TableSelectAll />
                </Table.Head>
                <Table.Head>Product</Table.Head>
                <Table.Head>Inventory</Table.Head>
                <Table.Head numeric>Price</Table.Head>
              </Table.Row>
            </Table.Header>
            <Table.Body>
              {PRODUCTS.map(([id, name, stock, price]) => (
                <Table.Row key={id}>
                  <Table.Cell>
                    <TableSelectRow
                      value={id}
                      form="products-bulk"
                      aria-label={`Select ${name}`}
                      defaultChecked={id === 'apron-002'}
                    />
                  </Table.Cell>
                  <Table.Head scope="row">{name}</Table.Head>
                  <Table.Cell>{stock}</Table.Cell>
                  <Table.Cell numeric>{MONEY.format(price)}</Table.Cell>
                </Table.Row>
              ))}
            </Table.Body>
          </Table.Root>
        </Table.Container>
      </TableSelection>
    </Stack>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

TableSelectAllProps type

import type { TableSelectAllProps } from '@nizivo/react/table-selection'

The props of TableSelectAll, listed above.

TableSelectRowProps type

import type { TableSelectRowProps } from '@nizivo/react/table-selection'

The props of TableSelectRow, listed above.

TableSelectionLabels type

import type { TableSelectionLabels } from '@nizivo/react/table-selection'

Row selection's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
selectAllrequired	string	'Select all rows'	The select-all checkbox's name.

TableSelectionProps type

import type { TableSelectionProps } from '@nizivo/react/table-selection'

The props of TableSelection, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

This stylesheet reads no public hook.

Layers: nz.components. Classes: .nz-table-selection.

AccessibilityCopy Anchor Link

Nothing in this component takes focus or keyboard input.

KeyboardCopy Anchor Link

Source: Native checkboxes; TableSelection's own listener for select-all, Shift-click and Escape. Checked by the browser lane (test/browser/table-selection.spec.tsx) in Chromium, Firefox and WebKit.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: none
• Ghost masters: none