Skip to main content

DataTable - Row Operations

Displays a matrix of information with columns, rows, and information that can operate dynamically.

Submit feedback
Edit this page
github
View source code
figma
View design
import { DataTable } from '@uhg-abyss/web/ui/DataTable';
import { useDataTable } from '@uhg-abyss/web/hooks/useDataTable';

Row selection​

To enable row selection, use the selectColumnConfig.selectionMode property. This accepts either 'single' or 'multi'.

const dataTableProps = useDataTable({
  // ...
  selectColumnConfig: { selectionMode: 'multi' },
  // ...
});

The dataTableProps.rowSelectionState.getSelectedRows function returns all information about the currently selected rows.

The dataTableProps.rowSelectionState.getSelectedRowIds function returns an array of the selected rows' IDs. These IDs are the uniqueId values provided for each row; refer to the Table data section for further information.

Single row selection​

Single row selection allows users to select only one row at a time using radio buttons.

Multi-row selection​

Multi-row selection allows users to select multiple rows at once using checkboxes. The selection column header contains a "Select All" checkbox that allows users to select all rows on the current page at once.

Note: The "Select All" checkbox only selects rows on the current page. This is intentional because it provides a better user experience and avoids issues that can arise from accidental bulk actions across pages users haven't viewed.

Teams wanting to select rows across all pages should implement their own logic to handle this use case. Can reference the programmatically select rows section to learn more.

Disabling row selection​

To disable row selection for specific rows, use the tableConfig.enableRowSelection function. This function receives the row data as an argument and should return a boolean value indicating whether the row is selectable. The example below disables selecting rows where the value of col4 is 'Completed'.

const dataTableProps = useDataTable({
  // ...
  tableConfig: {
    enableRowSelection: (row) => {
      return row.original.col4 !== 'Completed';
    },
  },
  // ...
});

Programmatically select rows​

To default certain rows to selected on initial render, use the initialStateConfig.initialSelectedRows property. This property accepts an object where the keys are the unique IDs of the rows and the values are booleans indicating whether that row should be selected.

const dataTableProps = useDataTable({
  // ...
  initialStateConfig: {
    initialSelectedRows: {
      '0': true,
      '1': true,
    },
    // ...
  },
});

To programmatically update which rows are selected, use setRowSelection method, which accepts the same object format as initialStateConfig.initialSelectedRows.

const dataTableProps = useDataTable({
  // ...
});


const selectRow = () => {
  dataTableProps.rowSelectionState.setRowSelection((prevSelection) => ({
    ...prevSelection,
    2: true,
  }));
};


// ...


return <Button onClick={selectRow}>Select Row 3</Button>;

Display settings​

Table settings dropdown​

The DataTable.TableSettingsDropdown subcomponent provides a dropdown menu for editing the table density (i.e., the height of the rows) as well as column visibility and order.

<DataTable.TableSettingsDropdown />

The available options are "Comfortable" (48px), "Cozy" (40px), or "Compact" (34px). The default value is "Comfortable", but this can be overridden with the defaultSettingConfig.rowHeight property.

const dataTableProps = useDataTable({
  // ...
  defaultSettingsConfig: { rowHeight: 'compact' },
  // ...
});

Note: It is not required to use DataTable.TableSettingsDropdown to take advantage of defaultSettingsConfig.rowHeight. Not using it simply means that users will not be able to configure the row height.

Row highlighting​

Configurable row highlighting​

Use the rowConfig.highlightConfig prop of the DataTable.Table sub-component to highlight rows. This prop accepts an object with the key rowsHighlighted, which is an array of objects with the row id to highlight (rowId). The rowId value should match the row.id used by the table (which is based on rowIdKey). If no color is provided, the default highlight color will be used.

Migration from uniqueId

If you're using uniqueId in your highlightConfig, update it to rowId. The uniqueId property is deprecated and will be removed in a future release.

Before:

rowsHighlighted: [{ uniqueId: '0', color: 'blue' }]

After:

rowsHighlighted: [{ rowId: '0', color: 'blue' }]
const highlightConfig = {
  rowsHighlighted: [
    {
      rowId: '0',
    },
    {
      rowId: '1',
      color: 'blue',
    },
    {
      rowId: '2',
    },
    {
      rowId: '3',
      color: 'yellow',
    },
  ];
};


//...


<DataTable.Table rowConfig={{ highlightConfig }} />;

Highlighting on hover​

Additionally, you can enable or disable highlighting on hover with the highlightConfig.highlightRowOnHover property.

const highlightConfig = {
  highlightRowOnHover: true;
};


/// ...


<DataTable.Table rowConfig={{ highlightConfig }} />;

Note: If a row is highlighted by default using rowsHighlighted, its highlight color will be overridden on hover.

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

DataTable Tokens

Token NameValue
data-table.color.border.column-header.drag
#002677
data-table.color.border.root
#CBCCCD
data-table.color.border.row.drag
#002677
data-table.color.border.table
#CBCCCD
data-table.color.icon.column-header-menus.grouping.active
#002677
data-table.color.icon.column-header-menus.grouping.hover
#004BA0
data-table.color.icon.column-header-menus.grouping.rest
#196ECF
data-table.color.icon.column-header-menus.sorting.active
#002677
data-table.color.icon.column-header-menus.sorting.hover
#004BA0
data-table.color.icon.column-header-menus.sorting.rest
#196ECF
data-table.color.icon.drag-handle.active
#002677
data-table.color.icon.drag-handle.hover
#004BA0
data-table.color.icon.drag-handle.rest
#196ECF
data-table.color.icon.expander.active
#002677
data-table.color.icon.expander.disabled
#7D7F81
data-table.color.icon.expander.hover
#004BA0
data-table.color.icon.expander.rest
#196ECF
data-table.color.icon.utility.drag-alternative.active
#000000
data-table.color.icon.utility.drag-alternative.disabled
#7D7F81
data-table.color.icon.utility.drag-alternative.hover
#323334
data-table.color.icon.utility.drag-alternative.rest
#4B4D4F
data-table.color.icon.utility.filter.active
#002677
data-table.color.icon.utility.filter.hover
#004BA0
data-table.color.icon.utility.filter.rest
#196ECF
data-table.color.surface.column-header.active
#E5F8FB
data-table.color.surface.column-header.default
#F3F3F3
data-table.color.surface.column-header.drag
#E5F8FB
data-table.color.surface.footer
#F3F3F3
data-table.color.surface.header
#FFFFFF
data-table.color.surface.root
#FFFFFF
data-table.color.surface.row.drag
#E5F8FB
data-table.color.surface.row.even
#FAFCFF
data-table.color.surface.row.highlighted
#E5F8FB
data-table.color.surface.row.hover
#F3F3F3
data-table.color.surface.row.odd
#FFFFFF
data-table.color.surface.table
#FFFFFF
data-table.color.text.cell
#4B4D4F
data-table.color.text.column-header
#4B4D4F
data-table.color.text.header.heading
#002677
data-table.color.text.header.paragraph
#4B4D4F
data-table.border-radius.all.container
8px
data-table.border-width.all.column-header.drag
2px
data-table.border-width.all.root
1px
data-table.border-width.all.row.drag
2px
data-table.border-width.all.table
1px
data-table.sizing.all.icon.column-header-menus
20px
data-table.sizing.all.icon.drag-handle-row
24px
data-table.sizing.all.icon.expander-column
24px
data-table.sizing.all.icon.utility.drag-alternative
20px
data-table.sizing.all.icon.utility.filter
20px
data-table.sizing.height.cell.comfortable
48px
data-table.sizing.height.cell.compact
32px
data-table.sizing.height.cell.cozy
40px
data-table.spacing.gap.horizontal.button-group
8px
data-table.spacing.gap.horizontal.cell
4px
data-table.spacing.gap.horizontal.drag-alternative
8px
data-table.spacing.gap.horizontal.input-container
8px
data-table.spacing.gap.horizontal.slot-wrapper
24px
data-table.spacing.gap.vertical.column-header
2px
data-table.spacing.gap.vertical.header
4px
data-table.spacing.gap.filter-two-inputs
16px
data-table.spacing.padding.all.column-header
8px
data-table.spacing.padding.all.column-header-menus
2px
data-table.spacing.padding.all.header
16px
data-table.spacing.padding.all.result-text
16px
data-table.spacing.padding.all.slot-wrapper
16px
data-table.spacing.padding.horizontal.cell
8px
data-table.spacing.padding.vertical.button-group
8px
data-table.spacing.padding.vertical.cell
4px
data-table.elevation.column.pinned.left
6px 0px 8px -2px rgba(0,0,0,0.16)
data-table.elevation.column.pinned.right
-6px 0px 8px -2px rgba(0,0,0,0.16)
data-table.elevation.column-header
0px 6px 8px -2px rgba(0,0,0,0.16)
data-table.elevation.table-settings-dropdown.section-header
0px 2px 4px -2px rgba(0,0,0,0.16)

Table of Contents