Feedback and status

Empty state

<forma-empty-state>

Explains an empty result and offers a useful recovery action without treating absence as failure.

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

Purpose

An empty state fills the space where a list, table or search result would be when there is nothing to show, and tells the user why and what to do next. Forma renders a centered, dashed-border section with a decorative symbol, a heading, supporting text and actions. The application decides that the result is truly empty (not loading, not failed, not unknown) and supplies the explanation and actions.

Use when

  • A collection has no records yet and the user can create the first one.
  • Filters or a search query exclude every record and the user can broaden them.
  • A queue or inbox has been fully worked and that is a normal, good outcome.

Avoid when

  • Data is still loading: use Skeleton or Spinner. Loading is not empty.
  • The request failed or the result is unknown: use Alert, Operation status or a fault pattern. Unknown is not empty.
  • Only part of the data could be retrieved: say so with State survivability rather than presenting the missing part as empty.

Behavior to know

  • The dashed border signals a placeholder region rather than a message about a problem.
  • Content is centered and generously padded, and the padding scales with viewport width.
  • The symbol is decorative; the heading carries the explanation.

Basic example

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

Canonical

Minimal empty state

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.

No results match these filters

Clear one or more filters or broaden the search to see records.

HTML · Minimal empty state Raw HTML for HTML · Minimal empty state
<forma-empty-state class="forma-component-tag">
<section class="forma-empty-state" aria-labelledby="empty-title">
  <div class="forma-empty-state__symbol" aria-hidden="true">□</div>
  <h3 id="empty-title">No results match these filters</h3>
  <p>Clear one or more filters or broaden the search to see records.</p>
  <button type="button">Clear filters</button>
</section>
</forma-empty-state>

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

Examples

Scenario

First use

A collection that has never had records. The heading names the object, the text says what it is for, and the primary action creates the first one.

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.

No vendors yet

Vendors you add here can be selected on purchase orders and invoices.

HTML · First use Raw HTML for HTML · First use
<forma-empty-state class="forma-component-tag">
  <section class="forma-empty-state" aria-labelledby="empty-state-first-use-title">
    <div class="forma-empty-state__symbol" aria-hidden="true">+</div>
    <h3 id="empty-state-first-use-title">No vendors yet</h3>
    <p>Vendors you add here can be selected on purchase orders and invoices.</p>
    <button type="button">Add vendor</button>
  </section>
</forma-empty-state>

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

Scenario

Search with no matches

A search that returned nothing. The query is repeated so the user can spot a typo, and two recovery actions are grouped in a Cluster: clear the search or open help.

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.

No records match "reconcilation"

Check the spelling, or search by record number instead.

Search tips
HTML · Search with no matches Raw HTML for HTML · Search with no matches
<forma-empty-state class="forma-component-tag">
  <section class="forma-empty-state" aria-labelledby="empty-state-search-no-matches-title">
    <div class="forma-empty-state__symbol" aria-hidden="true">?</div>
    <h3 id="empty-state-search-no-matches-title">No records match "reconcilation"</h3>
    <p>Check the spelling, or search by record number instead.</p>
    <div class="forma-cluster">
      <button type="button">Clear search</button>
      <a class="forma-button" href="#empty-state-search-no-matches-title">Search tips</a>
    </div>
  </section>
</forma-empty-state>

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

Scenario

Work queue cleared

An empty queue that is a good outcome. There is no action to take, so the empty state has only a heading and text; it must not look or read like an error.

Nothing waiting for review

New items assigned to you will appear here.

HTML · Work queue cleared Raw HTML for HTML · Work queue cleared
<forma-empty-state class="forma-component-tag">
  <section class="forma-empty-state" aria-labelledby="empty-state-queue-complete-title">
    <div class="forma-empty-state__symbol" aria-hidden="true">✓</div>
    <h3 id="empty-state-queue-complete-title">Nothing waiting for review</h3>
    <p>New items assigned to you will appear here.</p>
  </section>
</forma-empty-state>

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 filtered list

A filtered list with no results at phone width, with a long heading and two actions.

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

  • Vertical padding scales with clamp(2rem, 8vw, 5rem), so the block is compact on phones and roomier on desktops.
  • The heading and text are centered and wrap; very long headings stay inside the dashed border.
  • Actions in a Cluster wrap onto separate lines when they do not fit side by side, and keep native 44px-tall touch targets.
  • Nothing scrolls horizontally at 320px in either orientation.
HTML · Mobile filtered list Raw HTML for HTML · Mobile filtered list
<forma-empty-state class="forma-component-tag">
  <section class="forma-empty-state" aria-labelledby="empty-state-mobile-filtered-list-title">
    <div class="forma-empty-state__symbol" aria-hidden="true">□</div>
    <h3 id="empty-state-mobile-filtered-list-title">No open invoices from Northwind Traders in the last 30 days</h3>
    <p>Change the date range or remove the vendor filter.</p>
    <div class="forma-cluster">
      <button type="button">Clear filters</button>
      <button type="button">Last 90 days</button>
    </div>
  </section>
</forma-empty-state>

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-empty-stateid of the heading—Names the section so it is exposed as a labelled region.
aria-hidden.forma-empty-state__symboltrue—Hides the decorative symbol.
typebuttonbutton—Keeps recovery actions from submitting a surrounding form.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-empty-stateBlock class—Root section: centered grid with dashed border and viewport-scaled vertical padding. Removes heading and paragraph margins.
.forma-empty-state__symbolElement class—Bordered 2rem square holding a short text glyph. Decorative.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the recovery actions. The empty state itself is not focusable.
Events
EventDescription
clickNative click on recovery buttons or links. The application performs the action.

Form behavior

Not a form control.

States

Empty state states
StateHow it is expressedPresentation
Empty with actionheading, text and one or more buttons or linksThe user can change the situation, such as adding a record or clearing filters.
Empty as a good outcomeheading and text onlyNothing needs doing; the text confirms that and says what will appear later.

Accessibility

Forma provides

  • Uses a labelled section with a real heading, so the empty region is discoverable by heading and landmark navigation.
  • Keeps the symbol decorative and relies on text for meaning.
  • Uses a dashed border rather than color to mark the region.

Your application supplies

  • Only render an empty state when the application knows the result is empty; show loading, error or unknown states otherwise.
  • Choose a heading level that fits the surrounding document outline.
  • When the empty state replaces results after a filter or search, announce the result count through an existing status region, since the empty state has no live role.

Responsive behavior

  • The grid centers every child and sizes to its container; there are no breakpoints.
  • Vertical padding is clamp(2rem, 8vw, 5rem) and horizontal padding is a fixed 1.25rem.
  • Long headings and text wrap within the border.

Motion

  • No animation: the empty state appears and disappears with the application's content change.

Usage guidance

Do

  • Explain why the result is empty in the user's terms (no records yet, filters too narrow, all done).
  • Offer the single most useful next action.

Avoid

  • Using the empty state as an error message or while data is still loading.
  • Illustrations or symbols that carry information the text does not.

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.