DataTable

import { DataTable } from '@uhg-abyss/web/ui/DataTable';
import { useDataTable } from '@uhg-abyss/web/hooks/useDataTable';

Individual row actions

DataTable provides a way to perform actions on individual rows. This is useful for operations like deleting or programmatically modifying a row's data.

Use the actionColumnConfig property to enable the Abyss-managed "Actions" column in the table. This property accepts an object with the following properties:

actionMode determines whether to display a button or a dropdown.
- 'button' allows for a single action per row.
- 'dropdown' allows for one or more actions per row.
items is either a single action object or an array of action objects, depending on the actionMode selected.

Each action item has the following properties:

Property	Description
`onClick`	`row`: The row being interacted with that you'll typically pass to `deleteRow` or `modifyRow` `deleteRow`: Function that deletes the specified row from the table `modifyRow`: Function that updates cells in the specified row; accepts the row and an object with updates `setRowSelection`: Function to programmatically set / clear the selected rows
`checkDisabled`	Optional function that determines if the item should be disabled for a particular row

Refer to Single action for more about the items object for actionMode: 'button'.

Refer to Multiple actions for more about the items object for actionMode: 'dropdown'.

Note: Both the deleteRow and modifyRow functions accept an optional Boolean parameter skipPageReset that, when false, will reset the current page to the first page after the action is performed. By default, this parameter is true (i.e., the table will remain on the current page after the action is performed). For example:

const dataTableProps = useDataTable({
  // ...
  actionColumnConfig: {
    actionMode: 'button',
    items: [
      {
        label: 'Delete',
        icon: { icon: 'delete', position: 'leading' },
        onClick: ({ deleteRow, row }) => {
          deleteRow(row, false); // Reset to first page after deletion
        },
        checkDisabled: (row) => {
          // Disable the action if the value of `col4` is 'Completed'
          return row.getValue('col4') === 'Completed';
        },
      },
    ],
  },
  // ...
});

Single action

items when actionMode is button

Property	Type	Description
`label`	`ReactNode` or `function`	The text or element displayed for this action
`icon`	`Object` or `function`	Refer to Button for more information
`variant`	`string`	Refer to Button for more information
`color`	`string`	Refer to Button for more information
`href`	`string`	Refer to Button for more information
`checkDisabled`	`function`	A function to determine if this action should be disabled
`onClick`	`function`	Handler called when the action is clicked

In this example, the action button is disabled if the value of col4 is "Completed". The label and icon are dynamic and will be changed based on if the row can be deleted or not.

Multiple actions

items when actionMode is dropdown

Property	Type	Description
`label`	`string` or `function`	The text displayed for this action
`icon`	`ReactElement` or `function`	Icon to display next to the label
`isSeparated`	`boolean`	If true, adds a divider after this action
`checkDisabled`	`function`	A function to determine if this action should be disabled
`checkHidden`	`function`	A function to determine if this action should be disabled based on the selected rows
`onClick`	`function`	Handler called when the action is clicked

In this example, we use a dropdown to provide three actions for each row:

Delete Row: Deletes the rows from the table. This action is never disabled.
Modify Cell: Changes the col4 field to "Modified Cell". This is disabled if the value of col4 is "Completed". The label and icon are dynamic and will be changed based on if that cell can be modified or not.
Modify Row: modifies the values of col1, col2, col3, and col4 to "Modified Col X".

You can completely remove actions from the dropdown menu using the checkHidden property. This is useful when an action doesn't make sense in a particular context and should not be shown at all, rather than just being disabled.

Note: If all actions are hidden, the menu button will be disabled.

In this example, we hide the "Delete Row" action if any selected row has a status of "Completed".

You can also pass a dropdownConfig object to customize the dropdown trigger

By default, users will still be able to open the dropdown even if all items are disabled. To prevent this behavior, set the disableWhenAllItemsDisabled property to true.

const dataTableProps = useDataTable({
  // ...
  actionColumnConfig: {
    actionMode: 'dropdown',
    dropdownConfig = {
      iconOnly: (
        <IconSymbol
          icon="more_vert"
          size="$data-table.sizing.all.icon.column-header-menus"
        />
      ),
      outline: false,
      disableWhenAllItemsDisabled: true,
    };
  },
  // ...
});

Bulk actions

The DataTable.BulkActionsDropdown sub-component provides a dropdown that allows users to perform an operation on multiple selected rows at once.

<DataTable.BulkActionsDropdown />

Note: This feature requires row selection to be enabled.

const bulkActions = [
  {
    onClick: ({ deleteSelectedRows }) => {
      deleteSelectedRows();
    },
    icon: <IconSymbol icon="delete" />,
    label: 'Delete Rows',
    // Disable deletion for rows with col4='Completed'
    checkDisabled: (rows) => {
      return rows.some((row) => row.col4 === 'Completed');
    },
  },
];

<DataTable.BulkActionsDropdown items={bulkActions} />;

Each bulk action item is defined similarly to the individual actions, but with some additional properties.

Property	Type	Description
`label`	`string` or `function`	The text displayed for this action
`icon`	`ReactElement` or `function`	Optional icon to display next to the label
`isSeparated`	`boolean`	If true, adds a divider after this action
`isSingle`	`boolean`	If true, this action is disabled when multiple rows are selected
`checkDisabled`	`function`	A function to determine if this action should be disabled based on the selected rows
`checkHidden`	`function`	A function to determine if this action should be disabled based on the selected rows
`onClick`	`function`	Handler called when the action is clicked. `deleteRow`: Deletes the specified row `modifyRow`: Updates cells in the specified row; accepts the row and an object with updates `deleteSelectedRows`: Deletes all selected rows `modifySelectedRows`: Updates cells in all selected rows; accepts an object with updates `getSelectedRowIds`: Gets the IDs of selected rows `getSelectedRows`: Gets the selected row objects `setRowSelection`: Function to programmatically set/clear the selected rows

Note: Both the deleteSelectedRows and modifySelectedRows functions accept an optional Boolean parameter skipPageReset that, when false, will reset the current page to the first page after the action is performed. By default, this parameter is true (i.e., the table will remain on the current page after the action is performed). For example:

const bulkActions = [
  {
    onClick: ({ deleteSelectedRows }) => {
      deleteSelectedRows(false);
    },
    icon: <IconSymbol icon="delete" />,
    label: 'Delete Rows',
    // Disable deletion for rows with col4='Completed'
    checkDisabled: (rows) => {
      return rows.some((row) => row.col4 === 'Completed');
    },
  },
];

In this example, we use a bulk actions dropdown with three actions:

Delete Rows: Deletes all selected rows from the table. This action is never disabled.
Modify Cell: Changes the col4 field to "Modified Completed" for all selected rows. This action is disabled if any selected row has col4 value of "Completed". The label and icon are dynamic and will be changed based on if that cell can be modified or not.
Modify Single Row: Changes col1 and col2 fields to "Single Row Modified". This action is only enabled when exactly one row is selected.

Note: If all actions are hidden, the menu button will be disabled.

In this example, we hide the "Delete Rows" action if any selected row has a status of "Completed".

Use the headerActionsDropdownConfig prop of the DataTable.Table sub-component to provide actions a user can perform on all cells in a specific column. This feature is useful for hiding columns, sorting, and more.

This prop accepts an object with the following properties:

hideColumnActions: An array of column IDs for which the actions should be hidden.
items: An array of action objects, similar to the individual actions.

const headerActionsDropdownConfig = {
  hideColumnActions:[
    'col2'
  ],
  items: [
    {
      predefinedAction: 'sortAsc',
      isSeparated: false,
    },
    {
      label: 'Custom Action',
      onClick: () => {
        console.log('Custom action clicked');
      },
      isSeparated: false,
    },
    {
      predefinedAction: 'sortDesc',
      isSeparated: true,
    },
  ];
}

Note: Refer to the Custom actions section below for more information on creating custom actions.

Built-in actions

There are eight built-in actions that can be used in the header actions dropdown:

clearFilter
clearSort
groupBy
hideColumn
showAllColumns
sortAsc
sortDesc
ungroupBy

Certain column settings will prevent certain actions from displaying in the dropdown for those columns. For example:

If enableHiding is false, hideColumn will be removed.
If enableSorting is false, sortAsc and sortDesc will be removed.
If enableFiltering is false, clearFilter will be removed.

In this example, sorting and filtering are enabled by default for all columns, but col1 has sorting disabled, col2 has hiding disabled, and col3 has filtering disabled. Take a look at each column's actions dropdown to see which actions are available.

Custom actions

There may be times when the built-in column header actions do not meet your needs. In these cases, you can create your own custom actions.

const headerActionsDropdownConfig = {
  hideColumnActions: [], // Array of column IDs to hide the actions for
  items: [
    {
      label: 'Custom Action', // The label for a custom menu item
      onClick: () => {
        // The onClick handler for the custom menu item
        console.log('Custom action clicked');
      },
      isSeparated: false, // Optional boolean to indicate if the item should be separated
    },
  ],
};

In this example, we add a custom action to the header actions dropdown to clear the global filter.

Header display settings

When using the header actions dropdown, you may want to hide the default sorting and grouping buttons. Use the hideSortingButton and hideGroupingButton properties in defaultSettingsConfig.headerDisplaySettings to achieve this. Both properties are false by default.

const dataTableProps = useDataTable({
  //...
  defaultSettingsConfig: {
    headerDisplaySettings: {
      hideSortingButton: true,
      hideGroupingButton: true,
    },
  },
  // ...
});

In this example, we remove the default sorting buttons. The header actions dropdown will still allow sorting, but the buttons will not be displayed in the header.

Component Tokens

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

Search tokens

DataTable Tokens

Token Name	Value
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)

Individual row actions​

Single action​

Multiple actions​

Bulk actions​

Header actions dropdown​

Built-in actions​

Custom actions​

Header display settings​

useDataTable

EditableTableCell

DataTable.Table

DataTable.TableSettingsDropdown

DataTable.GlobalFilter

DataTable.DownloadDropdown

DataTable.BulkActionsDropdown

DataTable.Pagination

DataTable.SlotWrapper

EditableTableCell

DataTable.Table

DataTable.TableSettingsDropdown

DataTable.GlobalFilter

DataTable.DownloadDropdown

DataTable.BulkActionsDropdown

DataTable.Pagination

DataTable.SlotWrapper

Component Tokens

DataTable Tokens

Overview

Migrating

Data

Columns

Row Operations

Sorting

Filtering

Pagination

Actions

Editable Data

Server Side Operations

Expansion

Drag and Drop

Miscellaneous

Examples