Workspaces and shells

Record header

<forma-record-header>

Persistent record identity, status, context, breadcrumbs, and legal actions with mobile action collapse.

Authoring tag
<forma-record-header>
Behavior owner
Application content
Canonical source
patterns/record-header.html

Purpose

A record header sits at the top of a record page and answers four questions at a glance: where am I (breadcrumbs), what is this (type and identifier), what state is it in (status as text), and what can I do (actions). Secondary actions collapse into a native details disclosure so the header stays compact without a script. Forma lays out identity on one side and actions on the other and stacks everything on phones; which actions appear, and whether they are legal for this record and user, is decided by the application.

Use when

  • A page shows one record (an invoice, a case, a customer) and users need its identity and status visible before they act.
  • The record has one or two primary actions and a few secondary ones.
  • The same header should work on a phone with every action still reachable.

Avoid when

  • The heading introduces a page section rather than a record: use Section heading.
  • The page is a collection of records: use Collection toolbar above a list or Data grid.
  • Secondary actions need arrow-key menu navigation or grouping: compose a Action menu instead of the built-in disclosure list.
  • Actions must stay pinned at the bottom of a phone screen: add a Mobile action bar.

Behavior to know

  • Two columns: identity (minmax(0, 1fr)) and actions (auto), aligned to the bottom edge.
  • The type label is small mono uppercase text above the identifier heading; status sits beside the title and wraps under it when space runs out.
  • Secondary actions live in a native details/summary with an absolutely positioned panel.
  • At 40rem and below the header is one column and every action becomes full width.

Basic example

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

Canonical

Minimal record header

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 links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Invoice

INV-1042

Overdue

Acme Manufacturing · Due October 4, 2026

More
HTML · Minimal record header Raw HTML for HTML · Minimal record header
<forma-record-header class="forma-component-tag">
<header class="forma-record-header">
  <div class="forma-record-header__main">
    <nav aria-label="Breadcrumb"><a href="#home">Home</a> <span aria-hidden="true">/</span> <a href="#records">Records</a></nav>
    <div class="forma-record-header__title">
      <div><span class="forma-record-header__type">Invoice</span><h2>INV-1042</h2></div>
      <span class="forma-status-lozenge" data-state="attention">Overdue</span>
    </div>
    <p>Acme Manufacturing · Due October 4, 2026</p>
  </div>
  <div class="forma-record-header__actions">
    <button type="button">Primary action</button>
    <details>
      <summary>More</summary>
      <div class="forma-record-header__menu"><button type="button">Export</button><button type="button">View history</button></div>
    </details>
  </div>
</header>
</forma-record-header>

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

Examples

Scenario

Blocked case with restricted actions

A case that is blocked on another team. Status is text with a symbol, the context line explains why, and the application renders only the actions that are legal now; there is no More menu because there are no secondary actions.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Case

CASE-4407

Blocked

Refund not received · Waiting on Payments team since 28 September

HTML · Blocked case with restricted actions Raw HTML for HTML · Blocked case with restricted actions
<forma-record-header class="forma-component-tag">
  <header class="forma-record-header">
    <div class="forma-record-header__main">
      <nav aria-label="Case breadcrumb"><a href="#record-header-blocked-case-home">Support</a> <span aria-hidden="true">/</span> <a href="#record-header-blocked-case-cases">Cases</a></nav>
      <div class="forma-record-header__title">
        <div><span class="forma-record-header__type">Case</span><h2>CASE-4407</h2></div>
        <span class="forma-status-lozenge" data-state="blocked">Blocked</span>
      </div>
      <p>Refund not received · Waiting on Payments team since 28 September</p>
    </div>
    <div class="forma-record-header__actions">
      <button type="button">Add note</button>
    </div>
  </header>
</forma-record-header>

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

Scenario

Long identifier and several secondary actions

Content stress: a long supplier name and a long reference number wrap in the identity column while the action column keeps its natural width. Four secondary actions are collapsed into the More disclosure.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Purchase order

PO-2026-EMEA-00041872-REV3

Awaiting approval

Hanseatische Maschinenbau- und Anlagentechnik GmbH · €48,200.00 · Requested by Lena Vogt

More
HTML · Long identifier and several secondary actions Raw HTML for HTML · Long identifier and several secondary actions
<forma-record-header class="forma-component-tag">
  <header class="forma-record-header">
    <div class="forma-record-header__main">
      <nav aria-label="Purchase order breadcrumb"><a href="#record-header-long-identity-home">Procurement</a> <span aria-hidden="true">/</span> <a href="#record-header-long-identity-orders">Purchase orders</a></nav>
      <div class="forma-record-header__title">
        <div><span class="forma-record-header__type">Purchase order</span><h2 style="overflow-wrap: anywhere">PO-2026-EMEA-00041872-REV3</h2></div>
        <span class="forma-status-lozenge" data-state="attention">Awaiting approval</span>
      </div>
      <p>Hanseatische Maschinenbau- und Anlagentechnik GmbH · €48,200.00 · Requested by Lena Vogt</p>
    </div>
    <div class="forma-record-header__actions">
      <button type="button">Approve</button>
      <button type="button">Request changes</button>
      <details>
        <summary>More</summary>
        <div class="forma-record-header__menu">
          <button type="button">Duplicate</button>
          <button type="button">Export PDF</button>
          <button type="button">View history</button>
          <button type="button">Cancel order</button>
        </div>
      </details>
    </div>
  </header>
</forma-record-header>

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

Mobile record with collapsed actions

At phone width identity comes first, then the primary action and the More disclosure as full-width rows.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. 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

  • At 40rem and below the header is one column: breadcrumbs, type, identifier, status and context first, then actions.
  • Every direct child of the actions area, including the More details, becomes full width, so each button and the summary are at least 2.75rem tall full-width touch targets.
  • The secondary action panel opens below the summary and is still absolutely positioned; place the header where the panel will not be clipped by an overflow container.
  • Breadcrumbs wrap at 0.75rem; keep them short or show only the parent on phones.
HTML · Mobile record with collapsed actions Raw HTML for HTML · Mobile record with collapsed actions
<forma-record-header class="forma-component-tag">
  <header class="forma-record-header">
    <div class="forma-record-header__main">
      <nav aria-label="Visit breadcrumb"><a href="#record-header-mobile-visits">Visits</a></nav>
      <div class="forma-record-header__title">
        <div><span class="forma-record-header__type">Inspection</span><h2>Visit 12</h2></div>
        <span class="forma-status-lozenge" data-state="ok">Complete</span>
      </div>
      <p>Pump station 4 · 2 October</p>
    </div>
    <div class="forma-record-header__actions">
      <button type="button">Share report</button>
      <details>
        <summary>More</summary>
        <div class="forma-record-header__menu"><button type="button">Reopen</button><button type="button">Download photos</button></div>
      </details>
    </div>
  </header>
</forma-record-header>

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 links point to placeholder destinations that do not exist on this site. 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-labelbreadcrumb navstring—Names the breadcrumb navigation, for example "Breadcrumb"; keep it unique on the page.
aria-hiddenbreadcrumb separatorstrue—Hides the decorative slash separators from assistive technology.
data-state.forma-status-lozengeok | attention | blocked | unknownabsentAdds the status symbol to the lozenge; the text remains the status.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-record-headerBlock class—Root two-column grid with a border; identity on the start side, actions on the end.
.forma-record-header__actionsElement class—Wrapping row of actions; a details inside it becomes the More disclosure.
.forma-record-header__mainElement class—Identity column: breadcrumb nav, title row and a context paragraph.
.forma-record-header__menuElement class—The secondary actions panel inside details; absolutely positioned at the inline end with full-width buttons.
.forma-record-header__titleElement class—Wrapping flex row holding the type and identifier block and the status.
.forma-record-header__typeElement class—Small mono uppercase record type label shown above the identifier.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through breadcrumb links, actions and the More summary in source order.
Enter / Space on MoreOpens or closes the secondary actions. Native details behavior.
Tab inside the panelMoves through the secondary action buttons. There is no arrow-key navigation or Escape handling; the panel is not a menu widget.
Events
EventDescription
toggleNative event fired by details when the More panel opens or closes.
clickNative click on action buttons; the application performs the action.

Form behavior

Not a form control.

States

Record header states
StateHow it is expressedPresentation
Status.forma-status-lozenge with data-stateText status with a symbol for ok, attention, blocked or unknown.
Secondary actions opendetails[open]The panel is shown below the More summary at the inline end.
Stacked@media (max-width: 40rem)One column; every action is full width.

Accessibility

Forma provides

  • Keeps identity before actions in source and visual order at every width.
  • Gives the More summary a 2.75rem minimum height and makes every action full width on phones.
  • Uses a native details element, so disclosure state is exposed and operated by the browser.

Your application supplies

  • Use a heading for the identifier at the correct level for the page.
  • Write status as text; do not rely on the lozenge symbol or color alone.
  • Render only actions that are legal for this record and user; explain unavailable actions in the context line rather than showing disabled buttons without a reason.
  • Label the breadcrumb nav and mark the current page link with aria-current if the record itself appears in the trail.
  • Close the More panel after an action runs; Forma does not.

Responsive behavior

  • Wide: minmax(0, 1fr) auto; the identity column wraps long names while actions keep their natural width.
  • At 40rem and below: one column, and every direct child of .forma-record-header__actions is 100% wide.
  • The title row wraps, so a long status moves under the identifier instead of overflowing.
  • Long unbroken identifiers need overflow-wrap: anywhere or a shorter display form; the header does not truncate.

Motion

  • No animation: the More panel appears and disappears with the native details state, without transition. Buttons keep only the base perceptual hover and press color change.

Usage guidance

Do

  • Keep one primary action visible and move rarely used actions into More.
  • Show the record type so identifiers from different record kinds are not confused.

Avoid

  • Hiding the only critical action inside More on phones.
  • Putting destructive actions first in the More list without a confirming Dialog.

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.