XDS — Design System

Table@xds/core v0.0.13 · XDSTable

Usage

Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.

ts
import {XDSTable} from '@xds/core/Table'

Best practices

Guidance	Practices
Do	Use density and divider variants to match the information density and scanning needs of your data.
Do	Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell.
Don't	Use a table for data without consistent columns — use a list or card layout for heterogeneous content.
Don't	Enable every plugin at once — add only the features your use case requires to keep the interface focused.

Sub-components

Table is a compound component with 10 sub-components.

XDSBaseTable

Unstyled structural table component with a plugin transform pipeline and a components prop for swapping in custom row/cell renderers.

Prop	Type	Description
data	T[]	Array of data items to render as rows.
columns	XDSTableColumn<T>[]	Column definitions. If omitted, columns are auto-generated from data object keys.
idKey	(keyof T & string) \| ((item: T) => string \| number)	Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.
plugins	TablePlugin<T>[]	Ordered array of plugins applied as a sequential transform pipeline.
components	{Row?: ComponentType<TableRowComponentProps>; Cell?: ComponentType<TableCellComponentProps>; HeaderCell?: ComponentType<TableHeaderCellComponentProps>}	Component overrides for row and cell elements. When provided, these components receive xstyle from plugin transforms.
children	ReactNode	Children mode — render rows directly in the tbody instead of using data-driven rendering.
tableProps	HTMLAttributes<HTMLTableElement>	Additional HTML attributes passed directly to the root <table> element.

XDSTable

Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support.

Prop	Type	Description
data	T[]	Array of data items to render as rows.
columns	XDSTableColumn<T>[]	Column definitions. If omitted, columns are auto-generated from data object keys.
idKey	(keyof T & string) \| ((item: T) => string \| number)	Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.
density	'compact' \| 'balanced' \| 'spacious' (default: 'balanced')	Row density controlling cell padding and font size.
dividers	'rows' \| 'columns' \| 'grid' \| 'none' (default: 'rows')	Divider style rendered between cells.
isStriped	boolean (default: false)	Applies a background wash to even-numbered rows.
hasHover	boolean (default: false)	Applies a hover highlight background to rows on pointer devices.
plugins	Record<string, TablePlugin<T>>	Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.
children	ReactNode	Children mode — render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

XDSTableCell

<td> wrapper that reads XDSTableContext to apply density padding, font size, and divider borders when used inside XDSTable.

Prop	Type	Description
children	ReactNode	Cell content.

XDSTableHeaderCell

<th> wrapper that reads XDSTableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside XDSTable.

Prop	Type	Description
children	ReactNode	Header cell content.

XDSTableRow

<tr> wrapper that reads XDSTableContext to apply striped, hover, and divider styles when used inside XDSTable.

Prop	Type	Description
childrenrequired	ReactNode	Row cell elements.

useXDSTableColumnSettings

Headless column visibility and ordering management for XDSTable. Provides filtered columns, toggle helpers, and pre-built XDSMultiSelector options for a column picker UI.

Prop	Type	Description
columnsrequired	XDSColumnSettingsOption[]	All available columns with metadata for the settings UI. Each entry has key, label, optional isAlwaysVisible and group.
activeColumnKeysrequired	string[]	Currently active column keys, in display order. Only columns with keys in this array are shown.
onChangeActiveColumnKeysrequired	(keys: string[]) => void	Called when active columns change (toggle, reorder).
defaultColumnKeys	string[]	Default column set for "Reset to default". When omitted, reset shows all columns.

useXDSTablePagination

Headless pagination plugin for XDSTable. Supports client-side slicing, server-side pagination, and cursor-based pagination. Renders XDSPagination controls automatically above, below, or both.

Prop	Type	Description
pagerequired	number	Current page number (1-based).
onPageChangerequired	(page: number) => void	Called when the page changes.
totalItems	number	Total number of items across all pages. Used to calculate total page count.
totalPages	number	Total number of pages. Use when you know the page count but not item count.
hasMore	boolean	Whether more pages exist. Use for cursor-based pagination where the total is unknown.
pageSize	number (default: 10)	Number of items per page.
onPageSizeChange	(pageSize: number) => void	Called when the user changes the page size. Shows a page size dropdown when provided with pageSizeOptions.
pageSizeOptions	number[]	Available page size options. Shows a page size selector when provided.
variant	'pages' \| 'count' \| 'compact' \| 'dots' \| 'none' (default: 'pages')	Visual variant for the pagination controls.
position	'below' \| 'above' \| 'both' \| 'none' (default: 'below')	Where to render pagination controls relative to the table.
align	'start' \| 'center' \| 'end' (default: 'center')	Horizontal alignment of the pagination controls.

useXDSTableSelection

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

Prop	Type	Description
getIsItemSelectedrequired	(item: T) => boolean	Returns whether the given item is currently selected.
onSelectItemrequired	(event: {item: T; isSelected: boolean}) => void	Called when a row checkbox is toggled. isSelected is the new desired state.
onSelectAllrequired	(event: {isAllSelected: boolean}) => void	Called when the select-all header checkbox is toggled.
getIsAllSelectedrequired	() => boolean	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.

useXDSTableSelectionState

State management companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically — disabled rows are frozen (preserved across select-all/deselect-all), non-selectable rows are excluded.

Prop	Type	Description
datarequired	T[]	The full data array rendered in the table.
idKeyrequired	(keyof T & string) \| ((item: T) => string)	Key extractor — property name or function returning a unique string ID.
selectedKeysrequired	Set<string>	Controlled set of selected item IDs.
setSelectedKeysrequired	Dispatch<SetStateAction<Set<string>>>	Setter for the controlled selected keys.
getIsItemSelectable	(item: T) => boolean (default: () => true)	Should this row show a checkbox? Non-selectable rows are excluded from select-all.
getIsItemEnabled	(item: T) => boolean (default: () => true)	Is this row checkbox interactive? Disabled rows are frozen — select-all preserves their state.

useXDSTableSortable

Headless multi-sort plugin for XDSTable. The consumer owns sort state and provides a callback. Shift+click enables secondary sort columns. Sort indicators render in header cells automatically.

Prop	Type	Description
sortrequired	XDSTableSortState<TSortKey>	Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.
onSortChangerequired	(sort: XDSTableSortState<TSortKey>) => void	Called when the user clicks a header cell to change sort.
allowUnsortedState	boolean (default: false)	Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.
isMultiSortEnabled	boolean (default: false)	Enable multi-sort via Shift+click. Regular click still replaces the entire sort state.

Examples

Common configurations, variations, and states.

Table — Column Settings

Table with a column visibility picker in the toolbar. Toggle columns on and off.

Table — Popover Filters

Table with popover filter controls triggered by icons in column headers.

Table — Grid Dividers

Compact table with grid dividers showing both row and column borders, suited for dense numeric data.

Table — In Card

Table composed inside a card with a heading, demonstrating container bleed alignment.

Table — Inline Filters

Table with inline filter controls rendered directly below each column header.

Table — Paginated Data

Paginated data table navigating through a larger dataset page by page.

Table — Resizable Columns

Table with draggable column resize handles. Drag the right edge of any header to resize.

Table — Rich Cell Content

Table with rich cell content using XDSLink for emails and XDSBadge for role labels.

Table — Row Selection

Table with row selection checkboxes and a select-all header checkbox.

Table — Sortable Columns

Table with sortable columns, click headers to sort ascending or descending.

Table — Striped Rows

Table with alternating row colors and hover highlighting for easy scanning.

Usage

import {XDSTable} from '@xds/core/Table'

Best practices

Guidance	Practices
Do	Use density and divider variants to match the information density and scanning needs of your data.
Do	Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell.
Don't	Use a table for data without consistent columns — use a list or card layout for heterogeneous content.
Don't	Enable every plugin at once — add only the features your use case requires to keep the interface focused.

Prop

Type

Description

data

T[]

Array of data items to render as rows.

columns

XDSTableColumn<T>[]

Column definitions. If omitted, columns are auto-generated from data object keys.

idKey

(keyof T & string) | ((item: T) => string | number)

Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.

plugins

TablePlugin<T>[]

Ordered array of plugins applied as a sequential transform pipeline.

components

{Row?: ComponentType<TableRowComponentProps>; Cell?: ComponentType<TableCellComponentProps>; HeaderCell?: ComponentType<TableHeaderCellComponentProps>}

Component overrides for row and cell elements. When provided, these components receive xstyle from plugin transforms.

children

ReactNode

Children mode — render rows directly in the tbody instead of using data-driven rendering.

tableProps

HTMLAttributes<HTMLTableElement>

Additional HTML attributes passed directly to the root <table> element.

Prop

Type

Description

data

T[]

Array of data items to render as rows.

columns

XDSTableColumn<T>[]

Column definitions. If omitted, columns are auto-generated from data object keys.

idKey

(keyof T & string) | ((item: T) => string | number)

Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.

density

'compact' | 'balanced' | 'spacious' (default: 'balanced')

Row density controlling cell padding and font size.

dividers

'rows' | 'columns' | 'grid' | 'none' (default: 'rows')

Divider style rendered between cells.

isStriped

boolean (default: false)

Applies a background wash to even-numbered rows.

hasHover

boolean (default: false)

Applies a hover highlight background to rows on pointer devices.

plugins

Record<string, TablePlugin<T>>

Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.

children

ReactNode

Children mode — render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.

xstyle

StyleXStyles

StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Prop

Type

Description

children

ReactNode

Cell content.

Prop

Type

Description

children

ReactNode

Header cell content.

Prop

Type

Description

childrenrequired

ReactNode

Row cell elements.

Prop

Type

Description

columnsrequired

XDSColumnSettingsOption[]

All available columns with metadata for the settings UI. Each entry has key, label, optional isAlwaysVisible and group.

activeColumnKeysrequired

string[]

Currently active column keys, in display order. Only columns with keys in this array are shown.

onChangeActiveColumnKeysrequired

(keys: string[]) => void

Called when active columns change (toggle, reorder).

defaultColumnKeys

string[]

Default column set for "Reset to default". When omitted, reset shows all columns.

Prop

Type

Description

pagerequired

number

Current page number (1-based).

onPageChangerequired

(page: number) => void

Called when the page changes.

totalItems

number

Total number of items across all pages. Used to calculate total page count.

totalPages

number

Total number of pages. Use when you know the page count but not item count.

hasMore

boolean

Whether more pages exist. Use for cursor-based pagination where the total is unknown.

pageSize

number (default: 10)

Number of items per page.

onPageSizeChange

(pageSize: number) => void

Called when the user changes the page size. Shows a page size dropdown when provided with pageSizeOptions.

pageSizeOptions

number[]

Available page size options. Shows a page size selector when provided.

variant

'pages' | 'count' | 'compact' | 'dots' | 'none' (default: 'pages')

Visual variant for the pagination controls.

position

'below' | 'above' | 'both' | 'none' (default: 'below')

Where to render pagination controls relative to the table.

align

'start' | 'center' | 'end' (default: 'center')

Horizontal alignment of the pagination controls.

Prop

Type

Description

getIsItemSelectedrequired

(item: T) => boolean

Returns whether the given item is currently selected.

onSelectItemrequired

(event: {item: T; isSelected: boolean}) => void

Called when a row checkbox is toggled. isSelected is the new desired state.

onSelectAllrequired

(event: {isAllSelected: boolean}) => void

Called when the select-all header checkbox is toggled.

getIsAllSelectedrequired

() => boolean

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.

Prop

Type

Description

datarequired

T[]

The full data array rendered in the table.

idKeyrequired

(keyof T & string) | ((item: T) => string)

Key extractor — property name or function returning a unique string ID.

selectedKeysrequired

Set<string>

Controlled set of selected item IDs.

setSelectedKeysrequired

Dispatch<SetStateAction<Set<string>>>

Setter for the controlled selected keys.

getIsItemSelectable

(item: T) => boolean (default: () => true)

Should this row show a checkbox? Non-selectable rows are excluded from select-all.

getIsItemEnabled

(item: T) => boolean (default: () => true)

Is this row checkbox interactive? Disabled rows are frozen — select-all preserves their state.

Prop

Type

Description

sortrequired

XDSTableSortState<TSortKey>

Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.

onSortChangerequired

(sort: XDSTableSortState<TSortKey>) => void

Called when the user clicks a header cell to change sort.

allowUnsortedState

boolean (default: false)

Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.

isMultiSortEnabled

boolean (default: false)

Enable multi-sort via Shift+click. Regular click still replaces the entire sort state.