BulkActionBar

Usage

<BulkActionBar
  label="Equipment actions"
  selection={selectionSnapshot}
  visibleIds={pageIds}
  actions={[{ id: "flag", label: "Flag for inspection" }]}
  onAction={(actionId, snapshot) => openReview(actionId, snapshot)}
  onClearSelection={() => setSelectedIds([])}
/>

Snapshot and scope

BulkSelectionSnapshot contains id, scope, ids, sourceId, sourceRevision, filterDescription, and capturedAt in epoch milliseconds. Scope is visible, selected, or all-matching. The bar displays the exact count, scope, source revision, filters, capture time, and count of selected IDs outside visibleIds.

Source, Filters, and Captured use the shared DescriptionList details layout with muted labels and right-aligned, wrapping values. Source identifiers and the capture time use monospace text. The capture time shows in UTC to the second (2026-09-30 12:00:00 UTC); the exact instant stays in the element's machine-readable dateTime.

The application supplies unique nonempty IDs and resolves their authority. All matching means an explicit resolved ID set, including matching records outside the current page. A remote result count or one loaded page cannot establish that set. DataGrid's page-selection behavior remains unchanged.

Invalid snapshot, visible, or action IDs produce readable errors and block bulk actions. Empty selections also block actions. Clear remains available to request recovery from a malformed selection unless the whole control is disabled. Actions can supply disabledReason to explain unavailable operations: it shows under the action, and is its description, while the action is disabled.

Confirmation and authority

onAction receives an independent frozen snapshot, including a frozen copy of its ID array. The callback does not change the selection or establish an outcome. Confirmation belongs to the application: review the exact count and source/filter context, then recheck current permission, source revision, and selected IDs before dispatch. Changed context requires another review.

onClearSelection requests a controlled update. If the application retains the supplied selection, the bar retains it too. For invalid or partial results after dispatch, pair the snapshot with BulkResults and JobStatus.

Props

Accessibility

• The forwarded HTMLDivElement ref targets a named, focusable region. When the focused action is disabled or withdrawn (during dispatch, or when the selection empties), focus stays in that region instead of falling to the page.
• Choose headingLevel (2–6, default 3) to fit the label into the hosting surface's heading outline. Long labels, identifiers and reasons wrap.
• Snapshot metadata uses native description-list relationships.
• Action reasons are associated with their buttons; controls wrap at narrow widths.
• Native buttons retain keyboard and disabled behavior, 24px targets, and visible focus.

Manifest entry

<BulkActionBar label="Equipment actions" selection={snapshot} visibleIds={pageIds} actions={[{id:"flag",label:"Flag for inspection"}]} onAction={reviewAction} />

{
  "description": "Displays an explicit equipment selection snapshot, off-page count, source and filter context, with controlled bulk action requests.",
  "props": {
    "label": {
      "type": "string",
      "required": true
    },
    "selection": {
      "type": "node",
      "required": true,
      "description": "BulkSelectionSnapshot: {id,scope:'visible'|'selected'|'all-matching',ids:readonly string[],sourceId,sourceRevision,filterDescription,capturedAt:number}. IDs must be unique and nonempty. The application resolves all matching IDs before supplying them."
    },
    "visibleIds": {
      "type": "array",
      "required": true,
      "description": "Unique current visible-page IDs, used to explain retained selection outside that page."
    },
    "actions": {
      "type": "array",
      "required": true,
      "description": "BulkAction[]: unique id, label, optional disabled, disabledReason and danger. A disabledReason shows under its action, as the action's description, only while the action is disabled."
    },
    "onAction": {
      "type": "function",
      "required": true,
      "description": "(actionId, snapshot) => void. Receives an independent frozen copy, including its frozen IDs. Confirmation and authority checks belong to the application."
    },
    "onClearSelection": {
      "type": "function",
      "description": "Requests clearing selection without changing it locally. Available to recover from malformed snapshots."
    },
    "disabled": {
      "type": "boolean",
      "default": false
    },
    "headingLevel": {
      "type": "number",
      "default": 3,
      "description": "Label heading level: 2, 3, 4, 5, or 6. Choose it for the hosting surface's heading hierarchy."
    },
    "className": {
      "type": "string"
    }
  },
  "composable_with": [
    "DataGrid",
    "ConfirmDialog",
    "BulkResults",
    "JobStatus",
    "DescriptionList"
  ],
  "never_inside": [
    "Button"
  ],
  "example": "<BulkActionBar label=\"Equipment actions\" selection={snapshot} visibleIds={pageIds} actions={[{id:\"flag\",label:\"Flag for inspection\"}]} onAction={reviewAction} />"
}