For AI agents: the complete documentation index is available at https://a3s-lab.github.io/UI/en/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/UI/en/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/UI/en/components/bulk-action-bar.md.
A3S UI
  • English
  • next

      • Bulk Action Bar

      Bulk Action Bar is a temporary command region for a collection with an active selection. It keeps the selected scope, eligibility, batch commands, and the way out of selection mode in one predictable place.

      Environment actions

      Production environments

      Three environments are selected; only two have archive permission.

      3 selected

      2 items can be archived

      Usage

      Keep the bar adjacent to the collection that owns the selection. Give the root a collection-specific accessible name, keep the exact selected count visible, and label each command with the number of eligible items when eligibility is partial. The host owns permission checks, confirmation, requests, optimistic updates, rollback, and retry.

      The controller can be loaded with the complete runtime or as a split entry:

      <script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/bulk-action-bar.min.js" defer></script>

      The integrated preview above is the canonical HTML, React, and Vue example. Its source disclosure keeps the install command, setup entry, and example file in one workspace; switch the tabs in the preview toolbar to copy the active file.

      Contract

      Part or APIPurpose
      data-bulk-selection / data-selected-countCommunicates the current count and scope.
      data-bulk-summaryCommunicates eligibility, progress, or a bounded result with text.
      data-bulk-actions / data-bulk-actionDefines native commands and stable integration values.
      data-bulk-clearLeaves selection mode and synchronizes a composed Data Grid.
      data-bulk-focus-returnOptional selector for the stable collection control that receives focus after the bar hides.
      getSelection() / setSelection() / clear()Reads or updates the controlled selection snapshot.
      setSummary()Updates the eligibility or result message without owning domain data.
      setPending() / complete()Owns local pending geometry and publishes the host lifecycle.
      refresh()Recollects action nodes after host-rendered DOM changes.

      setPending(action, true, { message, allowClear }) disables the pending command and every contradictory command while retaining the original disabled states. allowClear defaults to true; set it to false when leaving selection mode would conflict with a host request. Clearing during pending does not cancel the request and preserves the pending region until the host completes it.

      States and recovery

      The live preview toolbar includes the state acceptance matrix. It verifies that empty hides the region, selected preserves the scope, loading disables contradictory commands, and disabled applies native disabled semantics to every command.

      Recoverable batch result

      2 selected

      Archive failed: production permission is missing. Retry after access is granted or clear selection.

      When five items are selected but only three are eligible, label the command “Retry 3”, not “Retry 5” followed by a silent server-side skip. Destructive commands still require Alert Dialog confirmation with the affected count.

      Accessibility and ownership

      The root region must be named for the collection it affects and must not move focus when it appears. Selection count, eligible count, progress, and outcome are expressed as text. The pending command keeps its label and exposes aria-busy="true" on the root; clear remains available only when allowClear permits it. After a rejected request, preserve the selection and focus context so the recovery command is still reachable. After a successful clear or completion, restore focus to the stable collection target instead of leaving focus on a hidden action.

      React and Vue use the same controller events and methods. They do not create a framework-specific selection store or perform network work inside the adapter.