Actions

Command group

<forma-command-group>

Groups related commands under an explicit, visible task label without owning command authority.

Authoring tag
<forma-command-group>
Category
Actions
Behavior owner
Application content
Canonical source
patterns/command-group.html

Purpose

A command group is a labelled section containing a heading and a wrapping row of native buttons. The heading names the task the commands serve (Edit, Share, Export), and aria-labelledby makes that name the group's accessible name, so a screen-reader user hears the context before the commands. Forma provides only layout: the label, the wrapping command row and a shared gap. Which commands exist, whether each is currently allowed, and what it does are application and Ordo decisions.

Use when

  • A toolbar or panel holds several families of commands and users need to know which family a command belongs to.
  • Commands would be ambiguous without context, for example two Delete buttons acting on different objects.
  • A record or document screen needs grouped actions that must stay visible and wrap on narrow screens.

Avoid when

Behavior to know

  • The visible heading is the group's accessible name through aria-labelledby.
  • Commands wrap onto new lines instead of shrinking; each keeps the 44px native button target.
  • One custom property, --forma-command-space, sets the gap between the label, the rows and the commands.
  • The group expresses no priority, legality or permission; it only arranges what the application renders.

Basic example

The smallest correct markup: the canonical pattern from patterns/command-group.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal command group

Rendered from the canonical pattern file.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Edit

HTML · Minimal command group Raw HTML for HTML · Minimal command group
<forma-command-group class="forma-component-tag">
<section class="forma-command-group" aria-labelledby="edit-commands">
  <h2 class="forma-command-group__label" id="edit-commands">Edit</h2>
  <div class="forma-command-group__commands">
    <button type="button">Cut</button><button type="button">Copy</button><button type="button">Paste</button>
  </div>
</section>
</forma-command-group>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Document toolbar with two groups

Two labelled groups side by side in a Cluster. Each section is named by its own heading, so the two sets of commands stay distinguishable in the landmark and heading lists even though both sit in one toolbar row.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Format

Share

HTML · Document toolbar with two groups Raw HTML for HTML · Document toolbar with two groups
<forma-command-group class="forma-component-tag">
  <div class="forma-cluster">
    <section class="forma-command-group" aria-labelledby="command-group-document-toolbar-format">
      <h2 class="forma-command-group__label" id="command-group-document-toolbar-format">Format</h2>
      <div class="forma-command-group__commands">
        <button type="button">Bold</button>
        <button type="button">Italic</button>
        <button type="button">Insert link</button>
      </div>
    </section>
    <section class="forma-command-group" aria-labelledby="command-group-document-toolbar-share">
      <h2 class="forma-command-group__label" id="command-group-document-toolbar-share">Share</h2>
      <div class="forma-command-group__commands">
        <button type="button">Copy link</button>
        <button type="button">Invite people</button>
      </div>
    </section>
  </div>
</forma-command-group>

Click or tap the code once to select all of it, then copy.

Scenario

Command unavailable with a visible reason

The application has decided Merge is not currently legal. The button is natively disabled, and a sentence inside the group states why, because the application-layer disabled button looks almost identical to an enabled one. Forma does not decide legality; it only renders the state it is given.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Pull request

Merge is unavailable: 2 required checks are still running.

HTML · Command unavailable with a visible reason Raw HTML for HTML · Command unavailable with a visible reason
<forma-command-group class="forma-component-tag">
  <section class="forma-command-group" aria-labelledby="command-group-unavailable-command-label">
    <h2 class="forma-command-group__label" id="command-group-unavailable-command-label">Pull request</h2>
    <div class="forma-command-group__commands">
      <button type="button">Request review</button>
      <button type="button" disabled>Merge</button>
      <button type="button">Close pull request</button>
    </div>
    <p class="forma-field__description">Merge is unavailable: 2 required checks are still running.</p>
  </section>
</forma-command-group>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Record commands on a phone

A group of five commands with longer labels at phone width. The commands wrap into several rows under the label; nothing is hidden or scrolled.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • forma-command-group__commands is a wrapping flex row, so commands move to new lines in source order instead of shrinking below 44px.
  • The label stays above the commands at every width; the group never becomes a horizontal scroller.
  • Long labels wrap inside their button. If the group grows too tall on phones, move rarely used commands into Overflow command disclosure rather than hiding them.
  • Orientation changes only reflow the rows; the order and grouping of commands are unchanged.
HTML · Record commands on a phone Raw HTML for HTML · Record commands on a phone
<forma-command-group class="forma-component-tag">
  <section class="forma-command-group" aria-labelledby="command-group-mobile-record-commands-label">
    <h2 class="forma-command-group__label" id="command-group-mobile-record-commands-label">Invoice INV-20931</h2>
    <div class="forma-command-group__commands">
      <button type="button">Send reminder</button>
      <button type="button">Record payment</button>
      <button type="button">Download PDF</button>
      <button type="button">Duplicate</button>
      <button type="button">Void invoice</button>
    </div>
  </section>
</forma-command-group>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelledbysection.forma-command-groupid of .forma-command-group__label—Required. Names the group from its visible heading so the region and its commands are announced with their task context.
id.forma-command-group__labelunique id—Target of aria-labelledby. Must be unique on the page.
typebuttonbutton—Commands are ordinary buttons; set type="button" so they never submit an enclosing form.
disabledbuttonbooleanabsentRenders an application-decided unavailable command. Pair it with visible text explaining why.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-command-groupBlock class—Root grid (usually a section) that stacks the label above the commands.
.forma-command-group__commandsElement class—Wrapping flex row that holds the command buttons.
.forma-command-group__labelElement class—The visible task label. Use a heading at the right level for the page outline; margins are reset and the size is reduced to a label size.
--forma-command-spaceCustom property—Gap between the label and the commands and between commands. Defaults to the spacing-2 token (0.5rem). Overflow command disclosure panels nested in the group inherit it.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the commands one by one in source order. Forma adds no arrow-key toolbar navigation; an ARIA toolbar with roving focus is application/Limen behavior.
Enter / SpaceActivates the focused command (native button behavior).
Events
EventDescription
clickNative click on each command button. The group itself emits nothing.

Form behavior

The group does not participate in forms. Commands are type="button"; if a command must submit, use type="submit" inside the form deliberately.

States

Command group states
StateHow it is expressedPresentation
Defaultmarkup as shownLabel above a wrapping row of commands.
Command unavailabledisabled attribute on a command buttonThe command is skipped by focus and cannot be activated. The application supplies the reason as text.
Wrappednarrow available widthCommands continue onto additional rows with the same gap.

Accessibility

Forma provides

  • Keeps commands as native buttons with their own focus, role and activation.
  • Keeps the label visible and above the commands at every width so the context is never lost.
  • Preserves 44px command targets by wrapping rather than shrinking.

Your application supplies

  • Name the group with a heading and aria-labelledby; a section without an accessible name is not exposed as a region.
  • Choose the heading level that fits the page outline.
  • Write command labels that make sense out of context, or include the object ("Void invoice").
  • If you implement ARIA role="toolbar" with arrow-key navigation, own that keyboard model in application/Limen code.
  • Explain unavailable commands in visible text and re-check legality when a command is activated.

Responsive behavior

  • Intrinsic sizing: the group is a single-column grid, and commands form a wrapping flex row.
  • No breakpoints; commands wrap in source order at any width and never overflow horizontally.
  • Long labels wrap inside their own buttons.
  • Place several groups in a Cluster or Stack to lay them out side by side or stacked.

Motion

  • No animation: the group itself does not move or transition. Its buttons keep the native button hover and press color feedback described on Button.

Usage guidance

Do

  • Use a short noun or verb phrase for the label that names the task (Share, Format, Invoice actions).
  • Keep the order of commands stable across records so users can find them by position as well as by name.

Avoid

  • Hiding a command because it is currently unavailable when users need to learn that it exists; render it disabled with a reason instead.
  • Using visual order or grouping to imply that a command is authorized or safe.
  • Nesting a command group inside another command group.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.