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
hiddenattribute 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: nowrapkeeps words separated as they are announced.- Choose
forma-visually-hiddenfor application markup;forma-sr-onlyis 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.
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.
<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
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
<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.
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.
<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.
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
<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.
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.
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.
<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.
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.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
aria-hidden | decorative glyph beside the hidden text | true | — | Hides the visible symbol from assistive technology so it is not announced alongside the hidden text. |
for | label.forma-visually-hidden | id of the field | — | A visually hidden label still labels its field and is still the click target's name. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-visually-hidden | Block 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-only | Block class | — | Assessment-layer utility with the same box plus clip-path: inset(50%), declared without !important, so a more specific rule can reveal it. |
| Keys | Result |
|---|---|
| None | The 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
| State | How it is expressed | Presentation |
|---|---|---|
| Hidden | class="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-hiddenuses!importantso 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-hiddenin application markup and keepforma-sr-onlywhere the assessment patterns already use it.
Avoid
- Hiding error messages, instructions or required markers that sighted users also need.
- Using
display: noneorhiddenfor 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.