What a selection can be done to: the live count, the actions, select all in view and Clear.
<div class="cap-bulk" data-cap="bulk-bar" role="region" aria-label="Bulk actions" id="bulk-static">
<p class="cap-bulk-count" role="status">3 selected <span class="cap-bulk-detail">2.4 MB</span></p>
<button type="button" class="cap-btn" data-variant="quiet" data-cap-part="select-all">Select all 24 in view</button>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="archive">Archive</button>
<span class="cap-bulk-field"><label for="bulk-static-tag">Tag</label><input class="cap-input" id="bulk-static-tag" list="bulk-static-tags" autocomplete="off" placeholder="tag name" /></span>
<datalist id="bulk-static-tags"><option value="release"></option><option value="field notes"></option></datalist>
<button type="button" class="cap-btn" data-cap-bulk-action="add-tag">Add tag</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-bulk-action="bin" data-destructive>Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
Installation
// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/bulk-bar.css";
import { enhance } from "capsomer/behavior/bulk-bar";
enhance();import "capsomer/tokens.css";
import "capsomer/bulk-bar.css";
import { BulkBar } from "capsomer/react/bulk-bar";Usage
<div class="cap-bulk" data-cap="bulk-bar" role="region" aria-label="Bulk actions">
<p class="cap-bulk-count" role="status">3 selected</p>
<div class="cap-bulk-actions">...buttons...</div>
<button class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div><div class="cap-bulk" data-cap="bulk-bar" data-cap-list="drafts" role="region" aria-label="Bulk actions" hidden>
<p class="cap-bulk-count" role="status">3 selected <span class="cap-bulk-detail">2.4 MB</span></p>
<button type="button" class="cap-btn" data-variant="quiet" data-cap-part="select-all" data-cap-label="Select all {n} in view">Select all 24 in view</button>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="archive" data-cap-said="Archived {n} draft{s}." data-cap-undone="Brought {n} draft{s} back.">Archive</button>
<span class="cap-bulk-field"><label for="tag">Tag</label><input class="cap-input" id="tag" /></span>
<button type="button" class="cap-btn" data-cap-bulk-action="add-tag" data-cap-value="#tag">Add tag</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-bulk-action="bin" data-destructive
data-cap-confirm-title="Bin {n} item{s}?" data-cap-confirm-lead="Binned drafts cannot be brought back."
data-cap-confirm-action="Bin {n} item{s}">Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
<label class="cap-check"><input type="checkbox" data-cap-select-all data-cap-list="drafts" /> Select all</label>
<ul id="drafts">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" value="p1" data-cap-select /> Notes on the spring release</label></li>
</ul><form id="drafts-form" method="post" action="/admin/posts/bulk">
<ul id="drafts-list"><li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" name="ids" value="p1" data-cap-select /> Notes on the spring release</label></li></ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="drafts-list" role="region" aria-label="Bulk actions">
<p class="cap-bulk-count" role="status">Tick the drafts to act on</p>
<div class="cap-bulk-actions">
<button type="submit" class="cap-btn" name="intent" value="archive">Archive</button>
<button type="submit" class="cap-btn" data-variant="danger" data-destructive name="intent" value="bin">Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
</form><div class="cap-bulk-results" data-cap-part="results" role="group" aria-labelledby="bulk-results">
<p class="cap-bulk-results-summary" id="bulk-results">2 done, 1 not done.</p>
<ul class="cap-bulk-results-list">
<li data-ok="false"><span class="cap-status" data-tone="crit">[glyph]Not done</span> <span class="cap-bulk-result-label">What a mention queue is for</span> <span class="cap-bulk-result-message">Changed on the site since this page was loaded.</span>
<ul class="cap-bulk-result-uses"><li>Notes on the spring release (cover image)</li></ul></li>
<li data-ok="true"><span class="cap-status" data-tone="ok">[glyph]Done</span> <span class="cap-bulk-result-label">Notes on the spring release</span></li>
</ul>
<button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-cap-part="dismiss-results" hidden>Dismiss results</button>
</div>import { enhance, bindBulk, performBulk, selectedItems, clearSelection } from "capsomer/behavior/bulk-bar";
enhance(); // every [data-cap="bulk-bar"]; needs a [data-cap="message"] region on the page for results
bindBulk(bar, {
archive: { run: (items) => api.archive(items.map((i) => i.id)), undo: (items) => api.restore(items.map((i) => i.id)) },
bin: { run: (items) => api.bin(items.map((i) => i.id)) }, // destructive: runs only after the preview
});
bar.addEventListener("cap-bulk-action", (e) => refresh(e.detail)); // { action, items, value }, after it ran
bar.addEventListener("cap-bulk-change", (e) => (e.detail.count)); // { items, count } on every changeimport { BulkBar } from "capsomer/react/bulk-bar";
<BulkBar items={selected} total={rows.length} onSelectAll={selectAll} onClear={clear} detail="2.4 MB"
actions={[
{ id: "archive", label: "Archive", said: "Archived {n} draft{s}.", run: archive, undo: restore },
{ id: "bin", label: "Bin", destructive: true, confirmTitle: "Bin {n} item{s}?", confirmAction: "Bin {n} item{s}", run: bin },
]} />Examples
Nothing selected: the bar is hidden
<p>The bar below is in the HTML with the <code>hidden</code> attribute, so it takes no room and is not read. It appears when the first item is chosen.</p>
<div class="bulk-head"><label class="cap-check"><input type="checkbox" data-cap-select-all data-cap-list="none-list" /> Select all drafts</label></div>
<ul class="bulk-list" id="none-list">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" value="n-1" data-cap-select /> Notes on the spring release</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Why the uptime strip counts gaps"><label class="cap-check"><input type="checkbox" value="n-2" data-cap-select /> Why the uptime strip counts gaps</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
<li data-label="What a mention queue is for"><label class="cap-check"><input type="checkbox" value="n-3" data-cap-select /> What a mention queue is for</label><span class="bulk-meta">Draft, edited 3 days ago</span></li>
</ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="none-list" role="region" aria-label="Bulk actions" id="bulk-none" hidden>
<p class="cap-bulk-count" role="status"></p>
<button type="button" class="cap-btn" data-variant="quiet" data-cap-part="select-all" data-cap-label="Select all {n} in view">Select all in view</button>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="archive" data-cap-label="Archive" data-cap-said="Archived {n} draft{s}." data-cap-undone="Brought {n} draft{s} back.">Archive</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-bulk-action="bin" data-destructive data-cap-label="Bin" data-cap-confirm-title="Bin {n} item{s}?" data-cap-confirm-lead="Binned drafts cannot be brought back." data-cap-confirm-action="Bin {n} item{s}" data-cap-said="Binned {n} draft{s}.">Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
Choose, then act: archive runs at once with Undo, bin previews first
<div class="bulk-head"><label class="cap-check"><input type="checkbox" data-cap-select-all data-cap-list="live-list" /> Select all drafts</label></div>
<ul class="bulk-list" id="live-list">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" value="d-1" data-cap-select /> Notes on the spring release</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Why the uptime strip counts gaps"><label class="cap-check"><input type="checkbox" value="d-2" data-cap-select /> Why the uptime strip counts gaps</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
<li data-label="What a mention queue is for"><label class="cap-check"><input type="checkbox" value="d-3" data-cap-select /> What a mention queue is for</label><span class="bulk-meta">Draft, edited 3 days ago</span></li>
<li data-label="Annual report: reading the charts"><label class="cap-check"><input type="checkbox" value="d-4" data-cap-select /> Annual report: reading the charts</label><span class="bulk-meta">Draft, edited 4 days ago</span></li>
<li data-label="Search without a server"><label class="cap-check"><input type="checkbox" value="d-5" data-cap-select /> Search without a server</label><span class="bulk-meta">Draft, edited 5 days ago</span></li>
</ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="live-list" role="region" aria-label="Bulk actions" id="bulk-live" hidden>
<p class="cap-bulk-count" role="status"></p>
<button type="button" class="cap-btn" data-variant="quiet" data-cap-part="select-all" data-cap-label="Select all {n} in view">Select all in view</button>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="archive" data-cap-label="Archive" data-cap-said="Archived {n} draft{s}." data-cap-undone="Brought {n} draft{s} back.">Archive</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-bulk-action="bin" data-destructive data-cap-label="Bin" data-cap-confirm-title="Bin {n} item{s}?" data-cap-confirm-lead="Binned drafts cannot be brought back." data-cap-confirm-action="Bin {n} item{s}" data-cap-said="Binned {n} draft{s}.">Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
A form: the actions are submit buttons and the server confirms
<p>This bar is in the page and works with no script: the boxes are the form's own, each action is a submit button named <code>intent</code>, and the server decides (a destructive intent gets the server's own page listing every item). With script the bar counts, hides while nothing is ticked, and refuses a press with nothing ticked.</p>
<form class="bulk-form" id="form-drafts" method="post" action="/admin/posts/bulk">
<ul class="bulk-list" id="form-list">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" name="ids" value="f-1" data-cap-select /> Notes on the spring release</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Why the uptime strip counts gaps"><label class="cap-check"><input type="checkbox" name="ids" value="f-2" data-cap-select /> Why the uptime strip counts gaps</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
<li data-label="What a mention queue is for"><label class="cap-check"><input type="checkbox" name="ids" value="f-3" data-cap-select /> What a mention queue is for</label><span class="bulk-meta">Draft, edited 3 days ago</span></li>
</ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="form-list" role="region" aria-label="Bulk actions" id="bulk-form">
<p class="cap-bulk-count" role="status">Tick the drafts to act on</p>
<div class="cap-bulk-actions">
<button type="submit" class="cap-btn" name="intent" value="archive">Archive</button>
<button type="submit" class="cap-btn" data-variant="danger" data-destructive name="intent" value="bin">Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
</form>
After an action: one outcome per item, refusals first
<p>The page the server sent back after the form posted: nothing is ticked, and the bar stays in view to list what happened to each item. Dismiss results needs script, so it is hidden in the delivered HTML and shown on load.</p>
<form class="bulk-form" id="outcome-drafts" method="post" action="/admin/posts/bulk">
<ul class="bulk-list" id="outcome-list">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" name="ids" value="o-1" data-cap-select /> Notes on the spring release</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Why the uptime strip counts gaps"><label class="cap-check"><input type="checkbox" name="ids" value="o-2" data-cap-select /> Why the uptime strip counts gaps</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
</ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="outcome-list" role="region" aria-label="Bulk actions" id="bulk-outcomes">
<p class="cap-bulk-count" role="status">Tick the drafts to act on</p>
<div class="cap-bulk-actions">
<button type="submit" class="cap-btn" name="intent" value="archive">Archive</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
<div class="cap-bulk-results" data-cap-part="results" role="group" aria-labelledby="bulk-outcomes-summary">
<p class="cap-bulk-results-summary" id="bulk-outcomes-summary">2 done, 1 not done.</p>
<ul class="cap-bulk-results-list">
<li data-ok="false"><span class="cap-status" data-tone="crit"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z"/></svg>Not done</span> <span class="cap-bulk-result-label">What a mention queue is for</span> <span class="cap-bulk-result-message">Changed on the site since this page was loaded. Open it to see the change.</span></li>
<li data-ok="true"><span class="cap-status" data-tone="ok"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1a7 7 0 1 0 0 14A7 7 0 1 0 8 1zM3.9 9l3 3 5.2-5.6-1.4-1.4-3.8 4.2-1.6-1.6z"/></svg>Done</span> <span class="cap-bulk-result-label">Notes on the spring release</span></li>
<li data-ok="true"><span class="cap-status" data-tone="ok"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1a7 7 0 1 0 0 14A7 7 0 1 0 8 1zM3.9 9l3 3 5.2-5.6-1.4-1.4-3.8 4.2-1.6-1.6z"/></svg>Done</span> <span class="cap-bulk-result-label">Why the uptime strip counts gaps</span></li>
</ul>
<button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-cap-part="dismiss-results" hidden>Dismiss results</button>
</div>
</div>
</form>
Twelve selected: the preview lists every one
<div class="bulk-head"><label class="cap-check"><input type="checkbox" data-cap-select-all data-cap-list="twelve-list" /> Select all drafts</label></div>
<ul class="bulk-list" id="twelve-list">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" value="t-1" data-cap-select checked /> Notes on the spring release</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Why the uptime strip counts gaps"><label class="cap-check"><input type="checkbox" value="t-2" data-cap-select checked /> Why the uptime strip counts gaps</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
<li data-label="What a mention queue is for"><label class="cap-check"><input type="checkbox" value="t-3" data-cap-select checked /> What a mention queue is for</label><span class="bulk-meta">Draft, edited 3 days ago</span></li>
<li data-label="Annual report: reading the charts"><label class="cap-check"><input type="checkbox" value="t-4" data-cap-select checked /> Annual report: reading the charts</label><span class="bulk-meta">Draft, edited 4 days ago</span></li>
<li data-label="Search without a server"><label class="cap-check"><input type="checkbox" value="t-5" data-cap-select checked /> Search without a server</label><span class="bulk-meta">Draft, edited 5 days ago</span></li>
<li data-label="A weekend with the media library"><label class="cap-check"><input type="checkbox" value="t-6" data-cap-select checked /> A weekend with the media library</label><span class="bulk-meta">Draft, edited 6 days ago</span></li>
<li data-label="Tokens, not hex codes"><label class="cap-check"><input type="checkbox" value="t-7" data-cap-select checked /> Tokens, not hex codes</label><span class="bulk-meta">Draft, edited 7 days ago</span></li>
<li data-label="Undo is cheaper than are-you-sure"><label class="cap-check"><input type="checkbox" value="t-8" data-cap-select checked /> Undo is cheaper than are-you-sure</label><span class="bulk-meta">Draft, edited 8 days ago</span></li>
<li data-label="Draft: the agent claims table"><label class="cap-check"><input type="checkbox" value="t-9" data-cap-select checked /> Draft: the agent claims table</label><span class="bulk-meta">Draft, edited 9 days ago</span></li>
<li data-label="Draft: a quieter status page"><label class="cap-check"><input type="checkbox" value="t-10" data-cap-select checked /> Draft: a quieter status page</label><span class="bulk-meta">Draft, edited 10 days ago</span></li>
<li data-label="Field notes from the migration"><label class="cap-check"><input type="checkbox" value="t-11" data-cap-select checked /> Field notes from the migration</label><span class="bulk-meta">Draft, edited 11 days ago</span></li>
<li data-label="Reading the CI logs aloud"><label class="cap-check"><input type="checkbox" value="t-12" data-cap-select checked /> Reading the CI logs aloud</label><span class="bulk-meta">Draft, edited 12 days ago</span></li>
</ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="twelve-list" role="region" aria-label="Bulk actions" id="bulk-twelve">
<p class="cap-bulk-count" role="status">12 selected</p>
<button type="button" class="cap-btn" data-variant="quiet" data-cap-part="select-all" data-cap-label="Select all {n} in view">Select all in view</button>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="archive" data-cap-label="Archive" data-cap-said="Archived {n} draft{s}." data-cap-undone="Brought {n} draft{s} back.">Archive</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-bulk-action="bin" data-destructive data-cap-label="Bin" data-cap-confirm-title="Bin {n} item{s}?" data-cap-confirm-lead="Binned drafts cannot be brought back." data-cap-confirm-action="Bin {n} item{s}" data-cap-said="Binned {n} draft{s}.">Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
An action that fails
<div class="bulk-head"><label class="cap-check"><input type="checkbox" data-cap-select-all data-cap-list="fail-list" /> Select all drafts</label></div>
<ul class="bulk-list" id="fail-list">
<li data-label="Annual report: reading the charts"><label class="cap-check"><input type="checkbox" value="f-1" data-cap-select checked /> Annual report: reading the charts</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Search without a server"><label class="cap-check"><input type="checkbox" value="f-2" data-cap-select checked /> Search without a server</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
<li data-label="A weekend with the media library"><label class="cap-check"><input type="checkbox" value="f-3" data-cap-select /> A weekend with the media library</label><span class="bulk-meta">Draft, edited 3 days ago</span></li>
</ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="fail-list" role="region" aria-label="Bulk actions" id="bulk-fail">
<p class="cap-bulk-count" role="status">2 selected</p>
<button type="button" class="cap-btn" data-variant="quiet" data-cap-part="select-all" data-cap-label="Select all {n} in view">Select all in view</button>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="publish" data-cap-label="Publish" data-cap-said="Published {n} draft{s}.">Publish</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-bulk-action="bin-fail" data-destructive data-cap-label="Bin" data-cap-confirm-title="Bin {n} item{s}?" data-cap-confirm-lead="Binned drafts cannot be brought back." data-cap-confirm-action="Bin {n} item{s}" data-cap-said="Binned {n} draft{s}.">Bin</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
Sticks to the bottom of its scroll area, or the top
<div class="bulk-scroll" id="bulk-scroll" tabindex="0" role="group" aria-label="Drafts, scrolling">
<div class="bulk-head"><label class="cap-check"><input type="checkbox" data-cap-select-all data-cap-list="sticky-list" /> Select all drafts</label></div>
<ul class="bulk-list" id="sticky-list">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" value="s-1" data-cap-select checked /> Notes on the spring release</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Why the uptime strip counts gaps"><label class="cap-check"><input type="checkbox" value="s-2" data-cap-select checked /> Why the uptime strip counts gaps</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
<li data-label="What a mention queue is for"><label class="cap-check"><input type="checkbox" value="s-3" data-cap-select /> What a mention queue is for</label><span class="bulk-meta">Draft, edited 3 days ago</span></li>
<li data-label="Annual report: reading the charts"><label class="cap-check"><input type="checkbox" value="s-4" data-cap-select /> Annual report: reading the charts</label><span class="bulk-meta">Draft, edited 4 days ago</span></li>
<li data-label="Search without a server"><label class="cap-check"><input type="checkbox" value="s-5" data-cap-select /> Search without a server</label><span class="bulk-meta">Draft, edited 5 days ago</span></li>
<li data-label="A weekend with the media library"><label class="cap-check"><input type="checkbox" value="s-6" data-cap-select /> A weekend with the media library</label><span class="bulk-meta">Draft, edited 6 days ago</span></li>
<li data-label="Tokens, not hex codes"><label class="cap-check"><input type="checkbox" value="s-7" data-cap-select /> Tokens, not hex codes</label><span class="bulk-meta">Draft, edited 7 days ago</span></li>
<li data-label="Undo is cheaper than are-you-sure"><label class="cap-check"><input type="checkbox" value="s-8" data-cap-select /> Undo is cheaper than are-you-sure</label><span class="bulk-meta">Draft, edited 8 days ago</span></li>
<li data-label="Draft: the agent claims table"><label class="cap-check"><input type="checkbox" value="s-9" data-cap-select /> Draft: the agent claims table</label><span class="bulk-meta">Draft, edited 9 days ago</span></li>
<li data-label="Draft: a quieter status page"><label class="cap-check"><input type="checkbox" value="s-10" data-cap-select /> Draft: a quieter status page</label><span class="bulk-meta">Draft, edited 10 days ago</span></li>
<li data-label="Field notes from the migration"><label class="cap-check"><input type="checkbox" value="s-11" data-cap-select /> Field notes from the migration</label><span class="bulk-meta">Draft, edited 11 days ago</span></li>
<li data-label="Reading the CI logs aloud"><label class="cap-check"><input type="checkbox" value="s-12" data-cap-select /> Reading the CI logs aloud</label><span class="bulk-meta">Draft, edited 12 days ago</span></li>
</ul>
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="sticky-list" role="region" aria-label="Bulk actions" id="bulk-sticky">
<p class="cap-bulk-count" role="status">2 selected</p>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="archive" data-cap-label="Archive" data-cap-said="Archived {n} draft{s}." data-cap-undone="Brought {n} draft{s} back.">Archive</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
</div>
<div class="bulk-scroll" id="bulk-scroll-top" tabindex="0" role="group" aria-label="Drafts, bar on top">
<div class="cap-bulk" data-cap="bulk-bar" data-cap-list="top-list" role="region" data-position="top" aria-label="Bulk actions" id="bulk-top">
<p class="cap-bulk-count" role="status">2 selected</p>
<div class="cap-bulk-actions">
<button type="button" class="cap-btn" data-cap-bulk-action="archive" data-cap-label="Archive" data-cap-said="Archived {n} draft{s}." data-cap-undone="Brought {n} draft{s} back.">Archive</button>
</div>
<button type="button" class="cap-btn cap-bulk-clear" data-variant="quiet">Clear selection</button>
</div>
<ul class="bulk-list" id="top-list">
<li data-label="Notes on the spring release"><label class="cap-check"><input type="checkbox" value="u-1" data-cap-select checked /> Notes on the spring release</label><span class="bulk-meta">Draft, edited 1 day ago</span></li>
<li data-label="Why the uptime strip counts gaps"><label class="cap-check"><input type="checkbox" value="u-2" data-cap-select checked /> Why the uptime strip counts gaps</label><span class="bulk-meta">Draft, edited 2 days ago</span></li>
<li data-label="What a mention queue is for"><label class="cap-check"><input type="checkbox" value="u-3" data-cap-select /> What a mention queue is for</label><span class="bulk-meta">Draft, edited 3 days ago</span></li>
<li data-label="Annual report: reading the charts"><label class="cap-check"><input type="checkbox" value="u-4" data-cap-select /> Annual report: reading the charts</label><span class="bulk-meta">Draft, edited 4 days ago</span></li>
<li data-label="Search without a server"><label class="cap-check"><input type="checkbox" value="u-5" data-cap-select /> Search without a server</label><span class="bulk-meta">Draft, edited 5 days ago</span></li>
<li data-label="A weekend with the media library"><label class="cap-check"><input type="checkbox" value="u-6" data-cap-select /> A weekend with the media library</label><span class="bulk-meta">Draft, edited 6 days ago</span></li>
<li data-label="Tokens, not hex codes"><label class="cap-check"><input type="checkbox" value="u-7" data-cap-select /> Tokens, not hex codes</label><span class="bulk-meta">Draft, edited 7 days ago</span></li>
<li data-label="Undo is cheaper than are-you-sure"><label class="cap-check"><input type="checkbox" value="u-8" data-cap-select /> Undo is cheaper than are-you-sure</label><span class="bulk-meta">Draft, edited 8 days ago</span></li>
<li data-label="Draft: the agent claims table"><label class="cap-check"><input type="checkbox" value="u-9" data-cap-select /> Draft: the agent claims table</label><span class="bulk-meta">Draft, edited 9 days ago</span></li>
<li data-label="Draft: a quieter status page"><label class="cap-check"><input type="checkbox" value="u-10" data-cap-select /> Draft: a quieter status page</label><span class="bulk-meta">Draft, edited 10 days ago</span></li>
<li data-label="Field notes from the migration"><label class="cap-check"><input type="checkbox" value="u-11" data-cap-select /> Field notes from the migration</label><span class="bulk-meta">Draft, edited 11 days ago</span></li>
<li data-label="Reading the CI logs aloud"><label class="cap-check"><input type="checkbox" value="u-12" data-cap-select /> Reading the CI logs aloud</label><span class="bulk-meta">Draft, edited 12 days ago</span></li>
</ul>
</div>
Results, where Undo lives
<div class="cap-message" data-cap="message" role="status" aria-label="Results and failures" aria-atomic="false"></div>
API reference
BulkBar
| Prop | Type | Required | Does |
|---|---|---|---|
items | readonly BulkItem[] | Yes | The selection. The bar is hidden (still rendered) while it is empty. |
actions | readonly BulkBarAction[] | Yes | |
onClear | () => void | Yes | Called after an action ran and by Clear selection: the app empties its selection. |
total | number | "Select all 24 in view": shown while fewer than total are selected. | |
onSelectAll | () => void | ||
detail | ReactNode | Quiet text after the count, such as the size: "2.4 MB". | |
position | "bottom" | "top" | ||
returnTo | HTMLElement | null | Where focus goes when the bar goes away. | |
children | ReactNode | Extra controls before the actions (a tag field). | |
label | string | ||
form | string | Form mode: the id of the form the selection belongs to (the checkboxes sit in it or name it with their own form). Actions with submit post it. The bar is in the delivered page without script and hides itself only after the page has loaded and nothing is ticked. | |
prompt | string | Form mode: the count's words before script runs, when nothing can be counted ("Tick the drafts to act on"). | |
outcomes | readonly BulkOutcome[] | The outcome of the action just run, one per item, refusals first. While there are any the bar stays in view with nothing selected, so they can be read; a server renders them after a form post, with no script. | |
onDismissOutcomes | () => void | Dismiss results: the app empties outcomes. Shown only once the page has loaded. |
Functions
| Function | Signature | Does |
|---|---|---|
useBulkSelection | (rows: readonly { id: string; }[]): BulkSelection | A React list's selection: stored ids, read through what is in view, so a filter or a new page never leaves a hidden row selected. |
countText | (n: number): string | "3 selected". |
fillCount | (template: string, n: number): string | Fills {n} and {s} in a template: "Bin {n} item{s}" gives "Bin 12 items" and "Bin 1 item". |
previewItems | (items: readonly BulkItem[]): string[] | Every item of a destructive action, one line each, for the confirm dialog's list. The title carries the count; the list is not shortened, because a preview that hides items is not one. |
orderOutcomes | (outcomes: readonly BulkOutcome[]): BulkOutcome[] | The outcomes to list, refusals first: what needs the person comes before what is done. |
outcomeSummary | (outcomes: readonly BulkOutcome[]): string | The outcome list's one line: "All 3 done.", "None done: 2 refused.", "2 done, 1 not done." |
visibleSelection | (selected: ReadonlySet<string>, rows: readonly { id: string; }[]): string[] | The selection model a React list keeps (a server-rendered list keeps it in its checkboxes). The one idea: the selection that counts is always the stored ids that are still in view, in the rows' order, so a filter that hides a row can never leave it counted, gated or submitted. |
allVisibleSelected | (selected: ReadonlySet<string>, rows: readonly { id: string; }[]): boolean | Every row in view is selected, and there is at least one (an empty page is not "all"). |
toggleAllVisible | (selected: ReadonlySet<string>, rows: readonly { id: string; }[]): Set<string> | Select all: the selection becomes exactly the rows in view; when they all are, it clears. Replacing, not merging, so no id out of view stays selected unseen. |
toggleOne | (selected: ReadonlySet<string>, id: string): Set<string> | |
failedIds | (outcomes: readonly BulkOutcome[]): Set<string> | After an action: exactly the items that were not done stay selected, so the next press retries those and nothing else. |
performBulk | (spec: BulkActionSpec): Promise<boolean> | Runs one bulk action the way the family does it. Resolves true when it ran, false when it was canceled or failed. Reversible: at once, then a message with Undo. Destructive: a confirm dialog lists every item, "Bin 12 items" performs, focus starts on Cancel. |
bindBulk | (bar: HTMLElement, actions: Record<string, BulkHandler>): void | Says what each action of a bar does. The keys are the buttons' data-cap-bulk-action values. |
listOf | (bar: HTMLElement): HTMLElement | null | |
boxesOf | (list: ParentNode): HTMLInputElement[] | The selectable items of a list: its checkboxes marked data-cap-select. |
labelOf | (box: HTMLInputElement): string | |
selectedItems | (bar: HTMLElement): BulkItem[] | The items now selected, in document order. An item that is out of sight (a filter hid it) is not acted on, so an action never reaches what the person cannot see. |
itemsInView | (list: ParentNode): HTMLInputElement[] | The selectable items the person can see now (a search or a filter may hide some). |
setAllInView | (list: ParentNode, on: boolean): void | Selects (or clears) every item in view. Real checkboxes change, so a form posts them. |
showOutcomes | (bar: HTMLElement, outcomes: readonly BulkOutcome[]): void | Writes the outcome list into the bar (the markup on the doc page), replacing any before it, and shows the bar. An empty list removes it. |
refresh | (bar: HTMLElement): number | Redraws the bar from the list: the count, hidden when there is none, the select-all label and the header checkbox's state. The count is written a frame after the bar appears, so a screen reader announces it (a status region that is shown and filled in one step is often missed). |
clearSelection | (bar: HTMLElement): void | Clears the selection. When focus was in the bar (which hides), it goes back to the list: the bar's data-cap-return selector, the item last touched, or the first item. |
invoke | (bar: HTMLElement, button: HTMLElement): Promise<boolean> | Presses one action button: the preview or the immediate run, as the button says. |
attachBulkBar | (bar: HTMLElement): () => void | |
enhance | (root?: ParentNode): () => void | Attaches to every [data-cap="bulk-bar"] under root not yet attached. Returns a function that detaches them all. |
Parts and data attributes
| Class | Is |
|---|---|
.cap-bulk | the root |
.cap-bulk-actions | a part |
.cap-bulk-clear | a part |
.cap-bulk-count | a part |
.cap-bulk-detail | a part |
.cap-bulk-field | a part |
.cap-bulk-result-label | a part |
.cap-bulk-result-message | a part |
.cap-bulk-result-uses | a part |
.cap-bulk-results | a part |
.cap-bulk-results-list | a part |
.cap-bulk-results-summary | a part |
| Attribute | Values |
|---|---|
data-cap-part | dismiss-results |
data-position | top |
| State | Read from |
|---|---|
[hidden] | an attribute |
Accessibility
| Key | Does |
|---|---|
| Tab, Shift Tab | Moves through Select all, the actions, any field, and Clear selection, in reading order |
| Enter or Space on an action | A reversible action runs at once and the region says so, with Undo; a destructive one opens the preview with focus on Cancel |
| Enter or Space on Clear selection | Clears the selection; focus returns to the list |
| Esc, in the list or the bar | Clears the selection; focus returns to the item last touched |
| Space, on an item's checkbox | Selects or clears it; the count follows |
| z | Runs the last action's Undo (the message region's key; off with the shortcuts switch, which sets data-cap-single-keys="off" on <html>) |
- The bar is
role="region"named "Bulk actions"; the count is arole="status"inside it, announced as it changes. - The preview is the confirm dialog:
role="alertdialog", named by its title, described by its lead and its list, focus on Cancel, Esc closes. - A destructive action is a word and a color (the danger variant), never color alone.
- The count and the detail reach 4.5:1; the bar's edge reaches 3:1; forced colors keep the edge.
- Hit areas are the buttons' own, at least
var(--target); density moves the bar's padding.