# ActionBar

A floating `role="toolbar"` of bulk actions that rests on the bottom edge of a table while rows are selected. Portals, follows its anchor, moves focus between actions with the arrow keys and announces the selection in a live region.

## Use for

- bulk actions for selected table rows
- a selection toolbar with a count and a clear button
- announcing how many rows are selected

## Practices

- Do: Pass `finalFocus` so focus has somewhere to go when the bar closes while it holds focus.
- Do: Inside a modal dialog, pass the dialog's popup as `portalRoot`.
- Do: Pass localized `announcement` and `openAnnouncement` strings, and a localized `aria-label` on `ActionBar.Dismiss`.
- Don't: Unmount the bar to hide it. Set `open={false}` so it can animate out and return focus.

## API reference

### ActionBar.Root

Positions the bar under `anchor`, kept inside the scrolling ancestor, and hides it when the anchor scrolls out of view. Stays mounted until the exit animation ends. Carries `data-open`, `data-starting-style` and `data-ending-style`.

Slot: `cl-action-bar`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Shows the bar. |
| `anchor` | `React.RefObject<HTMLElement \| null>` |  | The table the bar rests on. |
| `portalRoot` | `HTMLElement \| null` |  | Where the bar is portalled. |
| `finalFocus` | `React.RefObject<HTMLElement \| null> \| (() => HTMLElement \| null)` |  | Where focus goes when the bar closes while holding it: an element ref, or a function returning one. |
| `announcement` | `string` |  | Announced when the selection changes while the bar is open, such as `3 selected`. |
| `openAnnouncement` | `string` | `` `announcement` `` | Announced when the bar opens. |
| `positionerXstyle` | `XStyle` |  | StyleX for the positioner around the bar, which carries `cl-action-bar-positioner`. |

### ActionBar.Action

A `Button` in the arrow-key group. Takes every `Button` prop; defaults to `ghost` and `md`. `color="negative"` gets the destructive style.

Slot: `cl-button`

### ActionBar.Count

The selection count. The bar is described by it through `aria-describedby`, so it owns its `id`.

Slot: `cl-action-bar-count`

### ActionBar.Separator

A vertical `role="separator"` between groups of actions.

Slot: `cl-action-bar-separator`

### ActionBar.Dismiss

A square icon `ActionBar.Action` with an X glyph, for clearing the selection.

Slot: `cl-action-bar-dismiss`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `'Clear selection'` | Accessible name. Pass a localized string. |

## Examples

### Bulk actions on a table

```tsx
<ActionBar.Root
  open={selected.length > 0}
  anchor={tableRef}
  finalFocus={tableRef}
  announcement={fill(m.selected, { count: selected.length })}
>
  <ActionBar.Count>{fill(m.selected, { count: selected.length })}</ActionBar.Count>
  <ActionBar.Separator />
  <ActionBar.Action color='negative' onClick={onRemove}>
    {m.remove}
  </ActionBar.Action>
  <ActionBar.Dismiss aria-label={m.clearSelection} onClick={onClear} />
</ActionBar.Root>
```

## Related

- [Table](/docs/components/table.md)
- [Button](/docs/components/button.md)
