Bulk Actions

What is this?

Bulk Actions triggers allow merchants to manage a selection and start actions that modify multiple selected items.

Variants

Without Pagination

Loading...

With Pagination

Loading...

Usage

import { useBulkActions, BulkActions } from '@vtex/admin-ui'

function Example() {
  const state = useBulkActions({ pageItems, totalItems })

  return (
    <BulkActions state={state}>
      <Button>Action 1</Button>
      <Button>Action 2</Button>
    </BulkActions>
  )
}

Props

UseBulkActionsParams

The props you can pass as a parameter to the useBulkActions hook.

Name	Type	Description	Required	Default
pageItems	T[] where T extends { id: string,number }	Items of the Page	✅	-
totalItems	number	The total number of items	✅	-
pageSize	number	The number of items per page	✅	-

BulkActionState

The props returned by the useBulkActions hook.

Name	Type	Description	Default
totalItems	number	The total number of items	-
pageIds	Array<string,number>	IDs from the page items	-
getSelectedIds	() => Array<string,number>	Returns the IDs from the selected items	-
pageSelectedItems	T[]	Return the selected items from the current page	-
isItemSelected	(item: T) => boolean	Returns whether the item is selected or not	-
isVisible	boolean	Whether the BulkAction component is visible or not	-
allSelected	boolean	Whether all the items are selected or not	-
setAllSelected	Dispatch<SetStateAction<boolean>>	Sets the allSelected state	-
root	boolean, 'indeterminate'	Represents the root checkbox state	-
setRoot	Dispatch<SetStateAction<boolean>>	Sets the root checkbox state	-
selectedItemsIds	Array<string, number>	Represents the state of the checkboxes	-
setSelectedItemsIds	Dispatch<SetStateAction<Array<string, number>>>	Sets the checkboxes state	-
selectionTree	SelectionTreeState<T>	Selection tree state to be used within SelectionTree component	-

BulkActions

It also receives the same properties as the div JSX element.

Name	Type	Description	Required	Default
state	BulkActionsState<T>	Bulk actions state	✅	-

Components

When to display bulk actions outside of the Bulk Actions component?

The Bulk Actions component appears once items are selected in a list. If the page doesn't include a list or if the action must be visible at all times, then include the bulk action in the header of a container. For example, besides manual selection, the Export action can be triggered by creating rules to select items through a button in the DataView header.

Variants

What Buttons should be in the Bulk Actions?

• The buttons within the Bulk Actions component should use the tertiary or criticalTertiary variants. Include actions that can be performed for multiple items even though their entire content is not visible to the merchant, such as:
  • Edit
  • Delete
  • Activate
  • Deactivate
  • Archive
  • Pause
  • Export

What to avoid:

• Don't include more than 4 actions. For example, prefer adding a single Edit action that leads to a Modal where the property to be altered can be selected.

Position

Where should the Bulk Actions be positioned?

Bulk Actions should overlay the DataView component, be anchored at the bottom of the viewport and be horizontally centered.

Read the Listing page template documentation for more information.

Behavior

What should happen when the Select All button is clicked?

When the Select All action is triggered, all the items of all pages are selected.

After the selection, the possibility of unselecting specific items depends on the API of the involved system. The ideal behavior is that the merchant can click on the Checkbox of specific selected items to unselect them.

However, the API might not support registering all the items. In this case, when clicking Select All, the Checkbox of all items must be selected and disabled. It should only be enabled when the merchant clicks Deselect All.

When should the Bulk Actions be visible?

The Bulk Actions component appears when the merchant selects the Checkbox of a list item and disappears only when all the items are unselected.

What to avoid:

• Except for the Delete action, don’t hide or clear the selection after an action is triggered.
• Don’t hide or clear the selection after the merchant navigates between pages in the list.

What should happen after a Button in the Bulk Actions is triggered?

• Actions that impact multiple items should display a confirmation Modal. If the action already requires an additional step to define rules, such as defining the property to be altered in an Edit action, this confirmation can be suppressed.
• When an action has been completed, items should remain selected (except for Delete actions), and a feedback Toast should appear.

When should a Button in the Bulk Actions be disabled?

Disable actions only when the reason they are disabled is clear and if in some condition they become enabled.

Read the Button documentation for more details.

Content

What should be the icon and the label of Buttons in the Bulk Actions?

All Buttons inside the Bulk Actions component should include an icon, except for the default Select All button. Labels should use a verb in the infinitive and an object.

Read the Button documentation for more details.

• What is this?
  • Variants