Utilities

Visually hidden

<forma-visually-hidden>

Keeps text available to assistive technology while removing it from the visual layout.

Authoring tag
<forma-visually-hidden>
Category
Utilities
Behavior owner
Native CSS
Canonical source
patterns/visually-hidden.html

Purpose

Visually hidden text is read by screen readers and used in accessible names, but takes no space on screen. Use it when the visual design already makes something clear to sighted users (an × icon on a filter chip, a column of Edit buttons beside their rows) and the same information must reach people who do not see it. Forma ships two equivalent utilities. forma-visually-hidden is the general utility, declared with !important so component rules cannot accidentally reveal it; it uses the legacy clip: rect(0 0 0 0). forma-sr-only comes from the assessment layer and adds the modern clip-path: inset(50%) without !important, so a more specific rule can override it. Both keep the element in the accessibility tree; neither hides anything from assistive technology.

Use when

  • An icon-only or symbol-only control needs a text name: "Remove filter: Region is Europe".
  • Repeated visible labels (Edit, Open) need context for screen reader users: "Edit invoice INV-1042".
  • A form field's purpose is clear visually (a search box beside a Search button) but it still needs a real label.
  • Table captions or column headers that are obvious visually but needed for navigation.

Avoid when

  • Content that should be hidden from everyone: use the hidden attribute or remove it.
  • Decorative content that should be hidden from assistive technology: use aria-hidden="true".
  • Focusable elements such as links and buttons: neither class reveals on focus, so a sighted keyboard user would focus something invisible. Use Skip link for skip links.
  • Instructions sighted users also need; show them as visible text, for example in a Text field hint.

Behavior to know

  • The element is taken out of flow (position: absolute) and shrunk to a clipped 1px box, so it adds no space and cannot be seen.
  • white-space: nowrap keeps words separated as they are announced.
  • Choose forma-visually-hidden for application markup; forma-sr-only is used by the assessment patterns and when a later rule must be able to reveal the text.

Basic example

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

Canonical

Minimal visually hidden

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.

HTML · Minimal visually hidden Raw HTML for HTML · Minimal visually hidden
<forma-visually-hidden class="forma-component-tag">
<button type="button">
  <span aria-hidden="true">×</span>
  <span class="forma-visually-hidden">Remove filter: Region is Europe</span>
</button>
</forma-visually-hidden>

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

Examples

Scenario

Repeated actions with context

Each row has a visible Edit button. The hidden suffix makes every accessible name unique ("Edit invoice INV-1042"), so a screen reader's list of buttons is usable.

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.

  • INV-1042, Acme Manufacturing
  • INV-1043, Northstar Labs
HTML · Repeated actions with context Raw HTML for HTML · Repeated actions with context
<forma-visually-hidden class="forma-component-tag">
  <ul class="forma-stack" data-density="compact" aria-label="Draft invoices">
    <li class="forma-cluster">
      <span>INV-1042, Acme Manufacturing</span>
      <button type="button">Edit<span class="forma-visually-hidden"> invoice INV-1042</span></button>
    </li>
    <li class="forma-cluster">
      <span>INV-1043, Northstar Labs</span>
      <button type="button">Edit<span class="forma-visually-hidden"> invoice INV-1043</span></button>
    </li>
  </ul>
</forma-visually-hidden>

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

Scenario

Search field with a hidden label

The Search button makes the field's purpose obvious on screen, but the input still needs a real label. The label is visually hidden and remains the input's accessible name; the placeholder is only an example query.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Search field with a hidden label Raw HTML for HTML · Search field with a hidden label
<forma-visually-hidden class="forma-component-tag">
  <form class="forma-cluster" role="search" aria-label="Customers">
    <label class="forma-visually-hidden" for="visually-hidden-search-label-query">Search customers</label>
    <input id="visually-hidden-search-label-query" name="q" type="search" placeholder="e.g. Northstar" autocomplete="off">
    <button type="submit">Search</button>
  </form>
</forma-visually-hidden>

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

Scenario

Trend symbols explained

Arrow glyphs are decorative and hidden with aria-hidden; forma-sr-only text states the direction in words. This is the form used by assessment and metric patterns.

Open incidents
Increased to 14
Median response time
Decreased to 38 minutes
HTML · Trend symbols explained Raw HTML for HTML · Trend symbols explained
<forma-visually-hidden class="forma-component-tag">
  <dl class="forma-stack" data-density="compact">
    <div>
      <dt>Open incidents</dt>
      <dd><span aria-hidden="true">▲</span><span class="forma-sr-only">Increased to</span> 14</dd>
    </div>
    <div>
      <dt>Median response time</dt>
      <dd><span aria-hidden="true">▼</span><span class="forma-sr-only">Decreased to</span> 38 minutes</dd>
    </div>
  </dl>
</forma-visually-hidden>

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

Icon toolbar on a phone

A compact toolbar of symbol buttons for a narrow screen. Each glyph is aria-hidden and each button is named by visually hidden text.

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

  • Hidden text takes no space, so icon buttons stay compact and the cluster wraps only when the buttons themselves no longer fit.
  • Buttons keep Forma's 44px minimum target even though their visible content is a single glyph.
  • Hidden text never causes horizontal overflow: it is clipped to 1px and taken out of flow at every width.
  • Voice control users say the hidden name ("Tap Archive message"); keep it close to what the icon suggests.
HTML · Icon toolbar on a phone Raw HTML for HTML · Icon toolbar on a phone
<forma-visually-hidden class="forma-component-tag">
  <div class="forma-cluster" role="toolbar" aria-label="Message actions">
    <button type="button"><span aria-hidden="true">↩</span><span class="forma-visually-hidden">Reply</span></button>
    <button type="button"><span aria-hidden="true">⇥</span><span class="forma-visually-hidden">Forward</span></button>
    <button type="button"><span aria-hidden="true">▣</span><span class="forma-visually-hidden">Archive message</span></button>
    <button type="button"><span aria-hidden="true">×</span><span class="forma-visually-hidden">Delete message</span></button>
  </div>
</forma-visually-hidden>

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-hiddendecorative glyph beside the hidden texttrue—Hides the visible symbol from assistive technology so it is not announced alongside the hidden text.
forlabel.forma-visually-hiddenid of the field—A visually hidden label still labels its field and is still the click target's name.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-visually-hiddenBlock class—General utility: absolute position, 1px box, -1px margin, no padding or border, overflow: hidden, clip: rect(0 0 0 0), white-space: nowrap, all !important.
.forma-sr-onlyBlock class—Assessment-layer utility with the same box plus clip-path: inset(50%), declared without !important, so a more specific rule can reveal it.
Keyboard interaction
KeysResult
NoneThe utilities add no keyboard behavior. Hidden text inside a button or label contributes to that control's name; do not put the class on a focusable element.

Form behavior

No form behavior. A visually hidden label still labels its control.

States

Visually hidden states
StateHow it is expressedPresentation
Hiddenclass="forma-visually-hidden" or class="forma-sr-only"Clipped to a 1px, out-of-flow box; present in the accessibility tree.

Accessibility

Forma provides

  • Removes text only visually: it stays in the DOM and accessibility tree, so screen readers read it and it contributes to accessible names.
  • Prevents hidden words from running together with white-space: nowrap.
  • forma-visually-hidden uses !important so component and theme rules cannot reveal it by accident.

Your application supplies

  • Write hidden text as it should be heard, including leading spaces when it continues visible text ("Edit" + " invoice INV-1042").
  • Pair visible symbols with aria-hidden="true" so they are not announced twice or as their Unicode name.
  • Never put the class on a focusable element; sighted keyboard users would lose the focus indicator.
  • Check that visible text and the accessible name start the same way, so voice control users can activate the control by what they see (WCAG 2.5.3).

Responsive behavior

  • Hidden text is out of flow and clipped at every width, so it never affects wrapping, layout or horizontal overflow.
  • No breakpoints or container queries apply; the text is equally hidden on phones and desktops.

Motion

  • No animation: the utilities are static and do not transition in or out.

Usage guidance

Do

  • Prefer visible text when there is room; hide text only when the visual context already carries the meaning.
  • Use forma-visually-hidden in application markup and keep forma-sr-only where the assessment patterns already use it.

Avoid

  • Hiding error messages, instructions or required markers that sighted users also need.
  • Using display: none or hidden for screen-reader text; both remove it from the accessibility tree.
  • Stuffing extra keywords into hidden text; announce only what sighted users can infer.

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.