+
+ /**
+ * Provides an accessible name when no row header labels the checkbox.
+ */
+ 'aria-label'?: string
+
+ /**
+ * References the row header or headers that label the checkbox. The
+ * selection action is automatically prepended to the referenced labels.
+ */
+ 'aria-labelledby'?: string
+}
+
+function TableRowSelection({
+ selected,
+ checkboxRef,
+ className,
+ disabled,
+ headers,
+ onToggleSelect,
+ 'aria-label': ariaLabel = 'Select row',
+ 'aria-labelledby': ariaLabelledBy,
+ ...rest
+}: TableRowSelectionProps) {
+ const actionLabelId = React.useId()
+ const group = useContext(TableGroupContext)
+ const resolvedHeaders = [group?.headerId, headers].filter(Boolean).join(' ') || undefined
+
+ return (
+ |
+ {ariaLabelledBy ? Select : null}
+ onToggleSelect?.()}
+ aria-label={ariaLabelledBy ? undefined : ariaLabel}
+ aria-labelledby={ariaLabelledBy ? `${actionLabelId} ${ariaLabelledBy}` : undefined}
+ />
+ |
+ )
+}
+
type TableCellPlaceholderProps = React.PropsWithChildren
function TableCellPlaceholder({children}: TableCellPlaceholderProps) {
@@ -413,7 +555,9 @@ export {
TableRow,
TableHeader,
TableSortHeader,
+ TableSelectionHeader,
TableCell,
+ TableRowSelection,
TableCellPlaceholder,
TableSkeleton,
}
diff --git a/packages/react/src/DataTable/__tests__/DataTableSelection.test.tsx b/packages/react/src/DataTable/__tests__/DataTableSelection.test.tsx
new file mode 100644
index 00000000000..ebf89cde3de
--- /dev/null
+++ b/packages/react/src/DataTable/__tests__/DataTableSelection.test.tsx
@@ -0,0 +1,586 @@
+import {render, screen, within} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import React, {act} from 'react'
+import {hydrateRoot, type Root} from 'react-dom/client'
+import {renderToString} from 'react-dom/server'
+import {describe, expect, it, vi} from 'vitest'
+import {DataTable, Table} from '../../DataTable'
+import type {Column} from '../column'
+import type {DataTableData, DataTableRowGroup} from '../row'
+import classes from '../Table.module.css'
+import {implementsClassName} from '../../utils/testing'
+
+interface Row {
+ id: string | number
+ name: string
+}
+
+const columns: Array> = [
+ {
+ header: 'Name',
+ field: 'name',
+ rowHeader: true,
+ sortBy: true,
+ },
+]
+
+const data: Array = [
+ {id: 1, name: 'Beta'},
+ {id: 2, name: 'Alpha'},
+ {id: '1', name: 'Gamma'},
+]
+
+describe('DataTable row selection', () => {
+ implementsClassName(
+ props => (
+
+ ),
+ classes.TableSelectionHeader,
+ )
+
+ it('supports uncontrolled row selection and preserves string and numeric IDs', async () => {
+ const user = userEvent.setup()
+ const onSelectionChange = vi.fn()
+ render(
+ ,
+ )
+
+ expect(screen.getByRole('checkbox', {name: 'Select Beta'})).toBeChecked()
+ expect(screen.getByRole('checkbox', {name: 'Select Gamma'})).not.toBeChecked()
+
+ await user.click(screen.getByRole('checkbox', {name: 'Select Gamma'}))
+
+ expect(screen.getByRole('checkbox', {name: 'Select Gamma'})).toBeChecked()
+ const selectedRows = onSelectionChange.mock.lastCall?.[0].selectedRows
+ expect(selectedRows).toEqual(new Set([1, '1']))
+ expect(selectedRows).not.toBe(data)
+ })
+
+ it('requests immutable updates in controlled mode', async () => {
+ const user = userEvent.setup()
+ const selectedRows = new Set([1])
+ const onSelectionChange = vi.fn()
+ const {rerender} = render(
+ ,
+ )
+
+ await user.click(screen.getByRole('checkbox', {name: 'Select Alpha'}))
+
+ const nextSelectedRows = onSelectionChange.mock.lastCall?.[0].selectedRows
+ expect(nextSelectedRows).toEqual(new Set([1, 2]))
+ expect(nextSelectedRows).not.toBe(selectedRows)
+ expect(selectedRows).toEqual(new Set([1]))
+ expect(screen.getByRole('checkbox', {name: 'Select Alpha'})).not.toBeChecked()
+
+ rerender(
+ ,
+ )
+ expect(screen.getByRole('checkbox', {name: 'Select Alpha'})).toBeChecked()
+ })
+
+ it.each(['flat', 'grouped', 'mixed'] as const)('round-trips successive controlled selections (%s)', async mode => {
+ const user = userEvent.setup()
+ const onSelectionChange = vi.fn()
+ const groups: Array> = [
+ {groupId: 'first', label: 'First', rows: data.slice(0, 1)},
+ {groupId: 'second', label: 'Second', rows: data.slice(1)},
+ ]
+ const rows: DataTableData = mode === 'flat' ? data : mode === 'grouped' ? groups : [data[0], groups[1]]
+ function ControlledTable() {
+ const [selectedRows, setSelectedRows] = React.useState>(() => new Set())
+ return (
+ {
+ onSelectionChange(event)
+ setSelectedRows(event.selectedRows)
+ }}
+ />
+ )
+ }
+ render()
+ const beta = screen.getByRole('checkbox', {name: 'Select Beta'})
+ const alpha = screen.getByRole('checkbox', {name: 'Select Alpha'})
+ const selectAll = screen.getByRole('checkbox', {name: 'Select rows'})
+
+ await user.click(beta)
+ expect(beta).toBeChecked()
+ await user.click(beta)
+ expect(beta).not.toBeChecked()
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set()})
+
+ await user.click(beta)
+ await user.click(alpha)
+ expect(beta).toBeChecked()
+ expect(alpha).toBeChecked()
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set([1, 2])})
+
+ await user.click(selectAll)
+ expect(selectAll).toBeChecked()
+ await user.click(beta)
+ expect(beta).not.toBeChecked()
+ expect(alpha).toBeChecked()
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set([2, '1'])})
+ await user.click(selectAll)
+ expect(selectAll).toBeChecked()
+ await user.click(selectAll)
+ expect(selectAll).not.toBeChecked()
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set()})
+ })
+
+ it('uses getRowId as the selection identity', async () => {
+ const user = userEvent.setup()
+ const onSelectionChange = vi.fn()
+ interface KeyedRow extends Row {
+ key: string
+ }
+ const rows: Array = [
+ {id: 1, key: 'beta-key', name: 'Beta'},
+ {id: 2, key: 'alpha-key', name: 'Alpha'},
+ ]
+ const keyedColumns: Array> = [
+ {
+ header: 'Name',
+ field: 'name',
+ rowHeader: true,
+ },
+ ]
+ render(
+ row.key}
+ defaultSelectedRows={new Set(['beta-key'])}
+ onSelectionChange={onSelectionChange}
+ />,
+ )
+
+ expect(screen.getByRole('checkbox', {name: 'Select Beta'})).toBeChecked()
+ await user.click(screen.getByRole('checkbox', {name: 'Select Alpha'}))
+ expect(onSelectionChange).toHaveBeenLastCalledWith({
+ selectedRows: new Set(['beta-key', 'alpha-key']),
+ })
+ })
+
+ it('selects remaining rows from a mixed state and clears all selected rows from an all-selected state', async () => {
+ const user = userEvent.setup()
+ render()
+
+ const selectAll = screen.getByRole('checkbox', {name: 'Select rows'})
+ expect(selectAll).not.toBeChecked()
+ expect(selectAll).toHaveProperty('indeterminate', true)
+ expect(selectAll).toHaveAccessibleDescription('Select all 3 rows')
+
+ await user.click(selectAll)
+
+ expect(selectAll).toBeChecked()
+ expect(selectAll).toHaveProperty('indeterminate', false)
+ for (const row of data) {
+ expect(screen.getByRole('checkbox', {name: `Select ${row.name}`})).toBeChecked()
+ }
+
+ await user.click(selectAll)
+
+ expect(selectAll).not.toBeChecked()
+ for (const row of data) {
+ expect(screen.getByRole('checkbox', {name: `Select ${row.name}`})).not.toBeChecked()
+ }
+ })
+
+ it('preserves selection by stable ID through sorting and replacement data references', async () => {
+ const user = userEvent.setup()
+ const {rerender} = render(
+ ,
+ )
+
+ await user.click(screen.getByRole('button', {name: 'Name'}))
+ expect(screen.getByRole('checkbox', {name: 'Select Beta'})).toBeChecked()
+
+ rerender( ({...row}))} columns={columns} rowSelection />)
+ expect(screen.getByRole('checkbox', {name: 'Select Beta'})).toBeChecked()
+ })
+
+ it('intersects effective selection with current rows without discarding missing IDs', async () => {
+ const user = userEvent.setup()
+ const onSelectionChange = vi.fn()
+ const {rerender} = render(
+ ([1, 99])}
+ onSelectionChange={onSelectionChange}
+ />,
+ )
+
+ const selectAll = screen.getByRole('checkbox', {name: 'Select rows'})
+ expect(selectAll).toBeChecked()
+ expect(selectAll).toHaveAccessibleDescription('Select all 1 row')
+ expect(onSelectionChange).not.toHaveBeenCalled()
+
+ await user.click(selectAll)
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set([99])})
+
+ rerender(
+ ,
+ )
+ expect(screen.getByRole('checkbox', {name: 'Select Returned'})).toBeChecked()
+ expect(onSelectionChange).toHaveBeenCalledTimes(1)
+ })
+
+ it('excludes non-selectable rows from selection totals and select-all actions', async () => {
+ const user = userEvent.setup()
+ const onSelectionChange = vi.fn()
+ render(
+ row.id !== 2}
+ onSelectionChange={onSelectionChange}
+ />,
+ )
+
+ const selectAll = screen.getByRole('checkbox', {name: 'Select rows'})
+ expect(selectAll).toHaveAccessibleDescription('Select all 2 rows')
+ expect(screen.getByRole('checkbox', {name: 'Select Alpha'})).toBeDisabled()
+
+ await user.click(selectAll)
+
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set([1, '1'])})
+ expect(screen.getByRole('checkbox', {name: 'Select Alpha'})).not.toBeChecked()
+ })
+
+ it('keeps a disabled selection column when no rows are selectable', () => {
+ render( false} />)
+
+ const selectAll = screen.getByRole('checkbox', {name: 'Select rows'})
+ expect(selectAll).toBeDisabled()
+ expect(selectAll).not.toBeChecked()
+ expect(selectAll).toHaveProperty('indeterminate', false)
+ expect(selectAll).not.toHaveAccessibleDescription()
+
+ for (const row of data) {
+ expect(screen.getByRole('checkbox', {name: `Select ${row.name}`})).toBeDisabled()
+ }
+ })
+
+ it('selects rows across groups and provides complete grouped header associations', async () => {
+ const user = userEvent.setup()
+ const groups: Array> = [
+ {
+ groupId: 'first',
+ label: 'First',
+ rows: data.slice(0, 2),
+ },
+ {
+ groupId: 'second',
+ label: 'Second',
+ rows: data.slice(2),
+ },
+ ]
+ render()
+
+ const selectAllHeader = screen.getByRole('columnheader', {name: 'Select rows'})
+ const groupHeader = screen.getByRole('columnheader', {name: /^First\s*, 2 rows$/})
+ const betaCheckbox = screen.getByRole('checkbox', {name: 'Select Beta'})
+ const selectionCell = betaCheckbox.closest('td')
+
+ expect(selectAllHeader).toBe(screen.getAllByRole('columnheader')[0])
+ expect(groupHeader).toHaveAttribute('colspan', '2')
+ expect(selectionCell).toHaveAttribute('headers', `${groupHeader.id} ${selectAllHeader.id}`)
+
+ await user.click(screen.getByRole('checkbox', {name: 'Select rows'}))
+
+ for (const row of data) {
+ expect(screen.getByRole('checkbox', {name: `Select ${row.name}`})).toBeChecked()
+ }
+ })
+
+ it('preserves focus on the mounted select-all checkbox', async () => {
+ const user = userEvent.setup()
+ render()
+ const selectAll = screen.getByRole('checkbox', {name: 'Select rows'})
+
+ await user.click(selectAll)
+
+ expect(selectAll).toHaveFocus()
+ expect(screen.getByRole('checkbox', {name: 'Select rows'})).toBe(selectAll)
+ })
+
+ it('selects all mixed bodies while preserving sorting boundaries and excluding disabled rows', async () => {
+ const user = userEvent.setup()
+ const onSelectionChange = vi.fn()
+ const mixed: DataTableData = [
+ ...data.slice(0, 2),
+ {groupId: 'group', label: 'Group', rows: [data[2], {id: 3, name: 'Delta'}]},
+ {id: 4, name: 'Omega'},
+ ]
+ const {container} = render(
+ row.id !== 1 && row.id !== 4}
+ onSelectionChange={onSelectionChange}
+ />,
+ )
+ const selectAll = screen.getByRole('checkbox', {name: 'Select rows'})
+ expect(selectAll).toHaveAccessibleDescription('Select all 3 rows')
+ await user.click(selectAll)
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set([2, '1', 3])})
+ expect(screen.getByRole('checkbox', {name: 'Select Beta'})).not.toBeChecked()
+ expect(screen.getByRole('checkbox', {name: 'Select Omega'})).toBeDisabled()
+
+ await user.click(screen.getByRole('button', {name: 'Name'}))
+ expect(screen.getAllByRole('rowheader').map(header => header.textContent)).toEqual([
+ 'Alpha',
+ 'Beta',
+ 'Delta',
+ 'Gamma',
+ 'Omega',
+ ])
+ expect(selectAll).toBeChecked()
+ expect(screen.getByRole('checkbox', {name: 'Select Gamma'})).toBeChecked()
+ expectSelectionAssociationsToBeComplete(container)
+ const header = screen.getByRole('columnheader', {name: 'Select rows'})
+ expect(screen.getByRole('checkbox', {name: 'Select Alpha'}).closest('td')).toHaveAttribute('headers', header.id)
+ const groupHeader = screen.getByRole('columnheader', {name: /^Group\s*, 2 rows$/})
+ expect(screen.getByRole('checkbox', {name: 'Select Gamma'}).closest('td')).toHaveAttribute(
+ 'headers',
+ `${groupHeader.id} ${header.id}`,
+ )
+ await user.click(selectAll)
+ expect(onSelectionChange).toHaveBeenLastCalledWith({selectedRows: new Set()})
+ })
+
+ it.each(['flat', 'grouped', 'mixed'] as const)(
+ 'preserves %s selection associations through hydration',
+ async mode => {
+ const groups: Array> = [
+ {
+ groupId: 'group',
+ label: 'Group',
+ rows: data,
+ },
+ ]
+ const rows: DataTableData =
+ mode === 'flat' ? data : mode === 'grouped' ? groups : [data[0], {...groups[0], rows: data.slice(1)}]
+ const tables = (
+ <>
+
+
+
+ )
+ const container = document.createElement('div')
+ const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+ container.innerHTML = renderToString(tables)
+ document.body.appendChild(container)
+ const recoverableErrors: unknown[] = []
+ let root: Root | undefined
+
+ try {
+ const serverAssociations = getSelectionAssociationGraph(container)
+ expectSelectionAssociationsToBeComplete(container)
+
+ await act(async () => {
+ root = hydrateRoot(container, tables, {
+ onRecoverableError: error => recoverableErrors.push(error),
+ })
+ })
+
+ expect(recoverableErrors).toEqual([])
+ expect(
+ consoleErrorSpy.mock.calls.every(([message]) =>
+ String(message).includes('useLayoutEffect does nothing on the server'),
+ ),
+ ).toBe(true)
+ expect(getSelectionAssociationGraph(container)).toEqual(serverAssociations)
+ expectSelectionAssociationsToBeComplete(container)
+ } finally {
+ consoleErrorSpy.mockRestore()
+ await act(async () => root?.unmount())
+ container.remove()
+ }
+ },
+ )
+
+ it('does not render selection controls unless row selection is enabled', () => {
+ render()
+
+ expect(screen.queryByRole('checkbox')).not.toBeInTheDocument()
+ expect(screen.getAllByRole('columnheader')).toHaveLength(columns.length)
+ expect(screen.getByRole('table')).toHaveStyle({
+ '--grid-template-columns': 'minmax(max-content, 1fr)',
+ } as Partial)
+ })
+})
+
+function getSelectionAssociationGraph(container: HTMLElement) {
+ return Array.from(
+ container.querySelectorAll(
+ '[data-component="Table.SelectionHeader"], [data-component="Table.RowSelection"], [aria-labelledby]',
+ ),
+ ).map(element => ({
+ id: element.id,
+ headers: element.getAttribute('headers'),
+ labelledBy: element.getAttribute('aria-labelledby'),
+ }))
+}
+
+function expectSelectionAssociationsToBeComplete(container: HTMLElement) {
+ const allIds = new Set(Array.from(container.querySelectorAll('[id]'), element => element.id))
+
+ for (const table of container.querySelectorAll('table')) {
+ const selectionHeader = table.querySelector('[data-component="Table.SelectionHeader"]')
+ expect(selectionHeader?.id).toBeTruthy()
+
+ for (const selectionCell of table.querySelectorAll('[data-component="Table.RowSelection"]')) {
+ const headerIds = selectionCell.getAttribute('headers')?.split(' ') ?? []
+ expect(headerIds).toContain(selectionHeader?.id)
+ expect(headerIds.every(id => allIds.has(id))).toBe(true)
+
+ const checkbox = selectionCell.querySelector('input[type="checkbox"]')
+ const labelIds = checkbox?.getAttribute('aria-labelledby')?.split(' ') ?? []
+ expect(labelIds.length).toBeGreaterThanOrEqual(2)
+ expect(labelIds.every(id => allIds.has(id))).toBe(true)
+ }
+ }
+}
+
+describe('Table selection parts', () => {
+ it('renders controlled, composable selection controls with stable identifiers and refs', async () => {
+ const user = userEvent.setup()
+ const headerCheckboxRef = React.createRef()
+ const rowCheckboxRef = React.createRef()
+ const onHeaderChange = vi.fn()
+ const onRowChange = vi.fn()
+ const {container} = render(
+
+
+
+
+
+ Name
+
+
+
+
+
+
+
+ Primer
+
+
+
+
,
+ )
+
+ expect(container.querySelector('[data-component="Table.SelectionHeader"]')).toBeInTheDocument()
+ expect(container.querySelector('[data-component="Table.RowSelection"]')).toBeInTheDocument()
+ expect(screen.getByRole('columnheader', {name: 'Select rows'})).toHaveClass(
+ 'TableHeader',
+ 'custom-selection-header',
+ )
+ expect(screen.getByRole('columnheader', {name: 'Name'})).toHaveClass('TableHeader', 'custom-header')
+ expect(screen.getByRole('columnheader', {name: 'Select rows'})).toHaveAttribute('scope', 'col')
+ expect(screen.getByRole('checkbox', {name: 'Select rows'})).toHaveProperty('indeterminate', true)
+ expect(screen.getByRole('checkbox', {name: 'Select Primer'})).toBeChecked()
+ expect(headerCheckboxRef.current).toBe(screen.getByRole('checkbox', {name: 'Select rows'}))
+ expect(rowCheckboxRef.current).toBe(screen.getByRole('checkbox', {name: 'Select Primer'}))
+ expect(within(screen.getByRole('cell', {name: 'Select Primer'})).getByRole('checkbox')).toHaveAttribute(
+ 'data-component',
+ 'Checkbox',
+ )
+ await user.click(screen.getByRole('checkbox', {name: 'Select rows'}))
+ await user.click(screen.getByRole('checkbox', {name: 'Select Primer'}))
+ expect(onHeaderChange).toHaveBeenCalledExactlyOnceWith()
+ expect(onRowChange).toHaveBeenCalledExactlyOnceWith()
+ })
+
+ it.each(['all', 'some', 'none'] as const)('maps header selection "%s" to native checkbox state', selection => {
+ render(
+ ,
+ )
+ const checkbox = screen.getByRole('checkbox', {name: 'Select rows'})
+ expect(checkbox).toHaveProperty('checked', selection === 'all')
+ expect(checkbox).toHaveProperty('indeterminate', selection === 'some')
+ })
+
+ it('does not request toggles for disabled selection parts', async () => {
+ const user = userEvent.setup()
+ const onToggleSelect = vi.fn()
+ render(
+ ,
+ )
+ for (const checkbox of screen.getAllByRole('checkbox')) {
+ expect(checkbox).toBeDisabled()
+ expect(checkbox).not.toBeChecked()
+ expect(checkbox).toHaveProperty('indeterminate', false)
+ await user.click(checkbox)
+ }
+ expect(onToggleSelect).not.toHaveBeenCalled()
+ })
+})
diff --git a/packages/react/src/DataTable/index.ts b/packages/react/src/DataTable/index.ts
index 070fe97757e..73707fd4d47 100644
--- a/packages/react/src/DataTable/index.ts
+++ b/packages/react/src/DataTable/index.ts
@@ -6,7 +6,9 @@ import {
TableBody,
TableRow,
TableHeader,
+ TableSelectionHeader,
TableCell,
+ TableRowSelection,
TableCellPlaceholder,
TableContainer,
TableTitle,
@@ -31,7 +33,9 @@ const Table: typeof TableImpl &
Body: typeof TableBody
Group: typeof TableGroup
Header: typeof TableHeader
+ SelectionHeader: typeof TableSelectionHeader
Row: typeof TableRow
+ RowSelection: typeof TableRowSelection
Cell: typeof TableCell
CellPlaceholder: typeof TableCellPlaceholder
Pagination: typeof Pagination
@@ -47,7 +51,9 @@ const Table: typeof TableImpl &
Body: TableBody,
Group: TableGroup,
Header: TableHeader,
+ SelectionHeader: TableSelectionHeader,
Row: TableRow,
+ RowSelection: TableRowSelection,
Cell: TableCell,
CellPlaceholder: TableCellPlaceholder,
Pagination,
@@ -62,7 +68,9 @@ export type {
TableBodyProps,
TableRowProps,
TableHeaderProps,
+ TableSelectionHeaderProps,
TableCellProps,
+ TableRowSelectionProps,
TableContainerProps,
TableTitleProps,
TableSubtitleProps,
@@ -72,5 +80,5 @@ export type {
export type {TableGroupProps} from './TableGroup'
export {createColumnHelper} from './column'
export type {Column, CellAlignment, ColumnWidth} from './column'
-export type {DataTableData, DataTableRowGroup, UniqueRow} from './row'
+export type {DataTableData, DataTableRowGroup, DataTableRowId, UniqueRow} from './row'
export type {ObjectPaths} from './utils'
diff --git a/packages/react/src/DataTable/row.ts b/packages/react/src/DataTable/row.ts
index b1c67940d87..6b2ebe32f1f 100644
--- a/packages/react/src/DataTable/row.ts
+++ b/packages/react/src/DataTable/row.ts
@@ -1,5 +1,7 @@
+export type DataTableRowId = string | number
+
export interface UniqueRow {
- id: string | number
+ id: DataTableRowId
}
export interface DataTableRowGroup {
diff --git a/packages/react/src/DataTable/useTable.ts b/packages/react/src/DataTable/useTable.ts
index 87916799bb5..7d6e50e4da3 100644
--- a/packages/react/src/DataTable/useTable.ts
+++ b/packages/react/src/DataTable/useTable.ts
@@ -1,8 +1,9 @@
import {useId, useState} from 'react'
import type {Column} from './column'
-import type {DataTableData, DataTableRowGroup, UniqueRow} from './row'
+import type {DataTableData, DataTableRowGroup, DataTableRowId, UniqueRow} from './row'
import {DEFAULT_SORT_DIRECTION, SortDirection, transition, strategies} from './sorting'
import type {ObjectPathValue} from './utils'
+import {useControllableState} from '../hooks/useControllableState'
interface TableConfig {
columns: Array>
@@ -10,7 +11,12 @@ interface TableConfig {
initialSortColumn?: string | number
initialSortDirection?: Exclude
externalSorting?: boolean
- getRowId: (rowData: Data) => string | number
+ getRowId: (rowData: Data) => DataTableRowId
+ rowSelection?: boolean
+ selectedRows?: ReadonlySet
+ defaultSelectedRows?: ReadonlySet
+ onSelectionChange?: ({selectedRows}: {selectedRows: Set}) => void
+ isRowSelectable?: (row: Data) => boolean
}
interface Table {
@@ -18,6 +24,16 @@ interface Table {
bodies: Array | RowGroup>
actions: {
sortBy: (header: Header) => void
+ toggleRowSelection: (row: Row) => void
+ toggleAllRows: () => void
+ }
+ selection: {
+ headerId: string
+ selectedRows: Set
+ allSelected: boolean
+ someSelected: boolean
+ selectableCount: number
+ selectedCount: number
}
gridTemplateColumns: React.CSSProperties['gridTemplateColumns']
}
@@ -32,7 +48,11 @@ interface Header {
interface Row {
type: 'row'
- id: string | number
+ id: DataTableRowId
+ selectionId: DataTableRowId
+ selectionLabelledBy: string | undefined
+ selected: boolean
+ selectable: boolean
getCells: () => Array>
getValue: () => Data
}
@@ -70,6 +90,11 @@ export function useTable({
initialSortDirection,
externalSorting,
getRowId,
+ rowSelection = false,
+ selectedRows: controlledSelectedRows,
+ defaultSelectedRows,
+ onSelectionChange,
+ isRowSelectable,
}: TableConfig): Table {
const tableId = useId()
const [rowOrder, setRowOrder] = useState>(data)
@@ -78,7 +103,15 @@ export function useTable({
const [sortByColumn, setSortByColumn] = useState(() => {
return getInitialSortState(columns, initialSortColumn, initialSortDirection)
})
- const {gridTemplateColumns} = useTableLayout(columns)
+ const [selectedRows, setSelectedRows] = useControllableState>({
+ name: 'DataTable selectedRows',
+ value: controlledSelectedRows,
+ defaultValue: () => defaultSelectedRows ?? new Set(),
+ onChange: nextSelectedRows => {
+ onSelectionChange?.({selectedRows: new Set(nextSelectedRows)})
+ },
+ })
+ const {gridTemplateColumns} = useTableLayout(columns, rowSelection)
// Reset the `sortByColumn` state if the columns change and that column is no
// longer provided
@@ -239,14 +272,20 @@ export function useTable({
function createRow(row: Data, rowIndex: number): Row {
const rowId = getRowId(row)
- const rowHeaderIds = hasGroups
- ? headers.flatMap((header, index) =>
- header.column.rowHeader ? [`${tableId}-row-${rowIndex}-header-${index}`] : [],
- )
- : []
+ const rowHeaderIds =
+ hasGroups || rowSelection
+ ? headers.flatMap((header, index) =>
+ header.column.rowHeader ? [`${tableId}-row-${rowIndex}-header-${index}`] : [],
+ )
+ : []
+ const selectable = rowSelection && (isRowSelectable?.(row) ?? true)
return {
type: 'row',
id: `${rowId}`,
+ selectionId: rowId,
+ selectionLabelledBy: rowHeaderIds.length > 0 ? rowHeaderIds.join(' ') : undefined,
+ selected: selectable && selectedRows.has(rowId),
+ selectable,
getValue() {
return row
},
@@ -255,7 +294,7 @@ export function useTable({
const rowHeader = header.column.rowHeader ?? false
return {
id: `${rowId}:${header.id}`,
- domId: hasGroups && rowHeader ? `${tableId}-row-${rowIndex}-header-${index}` : undefined,
+ domId: (hasGroups || rowSelection) && rowHeader ? `${tableId}-row-${rowIndex}-header-${index}` : undefined,
headers: hasGroups ? (rowHeader ? [header.domId] : [...rowHeaderIds, header.domId]).join(' ') : undefined,
column: header.column,
rowHeader,
@@ -298,10 +337,59 @@ export function useTable({
if (body.rows.length > 0 || bodies.length === 0) {
bodies.push(body)
}
+ const allRows = bodies.flatMap(body => body.rows)
+ const selectableRows = allRows.filter(row => row.selectable)
+ const effectiveSelectedRows = new Set(selectableRows.filter(row => row.selected).map(row => row.selectionId))
+ const selectedCount = effectiveSelectedRows.size
+ const selectableCount = selectableRows.length
+ const allSelected = selectableCount > 0 && selectedCount === selectableCount
+ const someSelected = selectedCount > 0 && !allSelected
+
+ function toggleRowSelection(row: Row) {
+ if (!row.selectable) {
+ return
+ }
+
+ const nextSelectedRows = new Set(selectedRows)
+ if (nextSelectedRows.has(row.selectionId)) {
+ nextSelectedRows.delete(row.selectionId)
+ } else {
+ nextSelectedRows.add(row.selectionId)
+ }
+ setSelectedRows(nextSelectedRows)
+ }
+
+ function toggleAllRows() {
+ if (selectableRows.length === 0) {
+ return
+ }
+
+ const nextSelectedRows = new Set(selectedRows)
+ for (const row of selectableRows) {
+ if (allSelected) {
+ nextSelectedRows.delete(row.selectionId)
+ } else {
+ nextSelectedRows.add(row.selectionId)
+ }
+ }
+ setSelectedRows(nextSelectedRows)
+ }
return {
headers,
- actions: {sortBy},
+ actions: {
+ sortBy,
+ toggleRowSelection,
+ toggleAllRows,
+ },
+ selection: {
+ headerId: `${tableId}-selection-column`,
+ selectedRows: effectiveSelectedRows,
+ allSelected,
+ someSelected,
+ selectableCount,
+ selectedCount,
+ },
gridTemplateColumns,
bodies,
}
@@ -384,9 +472,12 @@ function getInitialSortState(
return null
}
-export function useTableLayout(columns: Array>): {gridTemplateColumns: string} {
+export function useTableLayout(
+ columns: Array>,
+ rowSelection = false,
+): {gridTemplateColumns: string} {
return {
- gridTemplateColumns: getGridTemplateFromColumns(columns).join(' '),
+ gridTemplateColumns: [...(rowSelection ? ['min-content'] : []), ...getGridTemplateFromColumns(columns)].join(' '),
}
}
diff --git a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
index 3bbe1e7c04a..d83c4636a30 100644
--- a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
+++ b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -328,6 +328,7 @@ exports[`@primer/react/experimental > should not update exports without a semver
"type DataTableData",
"type DataTableProps",
"type DataTableRowGroup",
+ "type DataTableRowId",
"default",
"default",
"DefaultFeatureFlags",
@@ -391,6 +392,8 @@ exports[`@primer/react/experimental > should not update exports without a semver
"type TableHeadProps",
"type TableProps",
"type TableRowProps",
+ "type TableRowSelectionProps",
+ "type TableSelectionHeaderProps",
"type TableSubtitleProps",
"type TableTitleProps",
"type TabListProps",
diff --git a/packages/react/src/experimental/index.ts b/packages/react/src/experimental/index.ts
index 2e935ae318e..3d7dc23cf6a 100644
--- a/packages/react/src/experimental/index.ts
+++ b/packages/react/src/experimental/index.ts
@@ -30,12 +30,15 @@ export type {
DataTableProps,
DataTableData,
DataTableRowGroup,
+ DataTableRowId,
TableProps,
TableHeadProps,
TableBodyProps,
TableRowProps,
TableHeaderProps,
+ TableSelectionHeaderProps,
TableCellProps,
+ TableRowSelectionProps,
TableContainerProps,
TableTitleProps,
TableSubtitleProps,