## Usage

The `<BulkActionBar />` component is used together with a table to implement a consistent bulk action experience. It displays a count of selected rows, [one or multiple actions](#one-or-multiple-actions) the user can make, and a "[Cancel](#cancel)" button.

NOTE: Refer to the [Bulk actions pattern](/patterns/tables/#bulk-actions) for guidelines and UX considerations to keep in mind when using this component.

```tsx live
const { headers, data } = placeholderTableData({ columns: 3, rows: 4 });
const [selectedValues, setSelectedValues] = useState<string[]>(['1']);
const [executionText, setExecutionText] = useState<string>();
const actions = [
  {
    label: 'Action 1',
    onClick: () => {
      setExecutionText(`"Action 1" is applied to rows ${JSON.stringify(selectedValues)}`);
    },
  },
  {
    label: 'Action 2',
    onClick: () => {
      setExecutionText(`"Action 2" is applied to rows ${JSON.stringify(selectedValues)}`);
    },
  },
];

const trigger = (ref: React.RefObject<HTMLButtonElement>, isOpen?: boolean, disabled?: boolean) => (
  <Button
    ref={ref}
    icon={isOpen ? ChevronUpIcon : ChevronDownIcon}
    iconPlacement="right"
    label="Bulk actions"
    tone="neutral"
    disabled={disabled}
    pressed={isOpen}
    block={{
      container: {
        xsmall: true,
        small: false,
      },
    }}
    size="small"
  />
);

return (
  <>
    {selectedValues.length > 0 && (
      <Box marginBottom="medium">
        <BulkActionBar selectedCount={selectedValues.length} onCancel={() => setSelectedValues([])}>
          <ActionsDropdown align="start" actions={actions} trigger={trigger} />
        </BulkActionBar>
      </Box>
    )}
    <Table selectType="checkbox" tableBorder selectedValues={selectedValues} onSelectedValuesChange={setSelectedValues}>
      <TableHead>
        <TableRow>
          {headers.map((columnName) => (
            <TableHeaderCell key={columnName} columnName={columnName.toLowerCase()}>
              {columnName}
            </TableHeaderCell>
          ))}
        </TableRow>
      </TableHead>
      <TableBody>
        {data.map(({ id, name, role }) => (
          <TableRow key={name} selectLabel={name} selectValue={id} selectDisabled={id === '3'}>
            <TableCell columnName="id">{id}</TableCell>
            <TableCell columnName="name">{name}</TableCell>
            <TableCell columnName="role">{role}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>

    <ResponseBlock prefix="Bulk action executed:" value={executionText} />
  </>
);
```

## Selected and total count

The `selectedCount` prop is always required and will render as "1 selected" for example.

Optionally, you can use the `totalCount` prop if you wish to display the selected count together with the total count. Together with selected count this will render as "1 / 3 selected".

## One or multiple actions

To provide the bulk action bar with actions, you have to pass the interactive element via `children`.

- **Single:** Use a [neutral Button](/packages/button/#neutral) if there is only one action available.
- **Multiple:** Use an [ActionsDropdown](/packages/actions/#actions-dropdown) with a neutral button (default) as `trigger` if there are many actions available.

```tsx live
const { headers, data } = placeholderTableData({ columns: 3, rows: 3 });
const [selectedValues, setSelectedValues] = useState<string[]>(['1']);
const selectAllValues = data.map((obj) => obj.id) as string[];
const { selectAll, onSelectAllChange } = useSelectAll(selectAllValues, selectedValues, setSelectedValues);
const [actionType, setActionType] = useState<string>('single');
const [executionText, setExecutionText] = useState<string>();

const actions = [
  {
    label: 'Retry',
    icon: SyncIcon,
    onClick: () => {
      setExecutionText(`"Retry" is applied to rows ${JSON.stringify(selectedValues)}`);
    },
  },
  {
    label: 'Ignore',
    icon: CloseCircleIcon,
    onClick: () => {
      setExecutionText(`"Ignore" is applied to rows ${JSON.stringify(selectedValues)}`);
    },
  },
];

const trigger = (ref: React.RefObject<HTMLButtonElement>, isOpen?: boolean, disabled?: boolean) => (
  <Button
    ref={ref}
    icon={isOpen ? ChevronUpIcon : ChevronDownIcon}
    iconPlacement="right"
    label="Bulk actions"
    tone="neutral"
    disabled={disabled}
    pressed={isOpen}
    block={{
      container: {
        xsmall: true,
        small: false,
      },
    }}
    size="small"
  />
);

return (
  <>
    <Flex flexDirection="column" gap="medium">
      <PlaygroundCard>
        <RadioGroup
          size="small"
          keepSpaceForMessage={false}
          horizontal
          value={actionType}
          onInputChange={(selectedValue) => setActionType(selectedValue)}
        >
          <Radio value="single">Single action</Radio>
          <Radio value="multiple">Multiple actions</Radio>
        </RadioGroup>
      </PlaygroundCard>

      <Flex flexDirection="column" gap="small">
        {selectedValues.length > 0 && (
          <BulkActionBar
            selectedCount={selectedValues.length}
            totalCount={data.length}
            onCancel={() => setSelectedValues([])}
          >
            {actionType === 'single' ? (
              <Button
                size="small"
                label="Send email notification"
                onClick={() => {
                  setExecutionText(`"Send email notification" is applied to rows ${JSON.stringify(selectedValues)}`);
                }}
                icon={MailIcon}
                tone="neutral"
              />
            ) : (
              <ActionsDropdown align="start" actions={actions} trigger={trigger} />
            )}
          </BulkActionBar>
        )}
        <Table selectType="checkbox" selectedValues={selectedValues} onSelectedValuesChange={setSelectedValues}>
          <TableHead>
            <TableRow selectAll={selectAll} onSelectAllChange={onSelectAllChange}>
              {headers.map((columnName) => (
                <TableHeaderCell key={columnName} columnName={columnName.toLowerCase()}>
                  {columnName}
                </TableHeaderCell>
              ))}
            </TableRow>
          </TableHead>
          <TableBody>
            {data.map(({ id, name, role }) => (
              <TableRow key={name} selectLabel={name} selectValue={id}>
                <TableCell columnName="id">{id}</TableCell>
                <TableCell columnName="name">{name}</TableCell>
                <TableCell columnName="role">{role}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </Flex>
    </Flex>
    <ResponseBlock prefix="Bulk action executed:" value={executionText} />
  </>
);
```

<Notice>
  <Text>
    If the bulk action is part of stepped user flow – i.e. there's only one bulk action that also takes the user to a
    new UI – then a bulk action bar component may not be needed. Instead, consider having a primary button to represent
    the bulk action placed below the table.
  </Text>
</Notice>

## Cancel

Use the `onCancel` prop to pass a function that gets invoked when the user presses the "Cancel" button.

Following the [Bulk actions pattern](/patterns/tables/#bulk-actions) it should:

- Clear all selections.
- Remove the bulk action bar from the UI.

## Placement in layout

The bulk action bar should always be placed directly above the table with a `small` (12px) gap between.

Enables the user to perform an action on multiple items at the same time.

BulkActionBar

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources