The moment a user opens a screen and finds nothing: a brand-new feature, a filter that excluded everything, or an inbox they just cleared. Empty states are teaching surfaces, not failure modes.
Empty means the product knows there is nothing to show. It is not a loading state, an error state, or a permissions message.
Five named parts. The headline and body are non-negotiable; actions depend on the type of empty state.
An icon or illustration that names the surface, such as an inbox, folder, or filter. Decorative only; the text must carry the meaning.
Use an existing Icon and mark it aria-hidden.
One short line that says what state the user is looking at. Use "No vendors yet," not "No data."
Name the missing object in the user's vocabulary.
One or two sentences that explain what would live here once it exists and how it gets there.
Keep the body instructional, not promotional.
Required for first-run states. For no-results, the primary action is usually "Clear filters" or the nearest equivalent.
Use a verb-object label the user recognizes.
A link to documentation, a sample, or a way to switch views. Only include it when it changes what a user would do next.
Do not add a secondary link just to fill space.
Pick the type first. A first-run surface, a failed filter, and an emptied inbox all look similar, but they are solving different user questions.
The user has never created or received anything here.
Trigger: A new account, a new feature, or a new tab the user is opening for the first time.
Job: Teach what would live here, then make the first action obvious.
The user's filter, search, or query returned nothing.
Trigger: A search box with no hits, a filter that excludes everything, or a date range with no entries.
Job: Acknowledge the query, suggest how to broaden it, and give a way back to the full view.
The user had things here and now they do not.
Trigger: Everything was archived, deleted, completed, or moved.
Job: Confirm what happened and how to recover or restore if relevant.
Render the same anatomy against different product contexts, then review the copy against the wrong/right pairs.
Vendor watchlist
Add vendors you want to track. You will see their status, insurance, and recent jobs here.
Vendor search
Try a shorter query, check the spelling, or clear filters to see all vendors.
Completed approvals
Approvals you finish will appear here for 90 days. Open requests stay in the Pending tab.
Vendor watchlist, first-run
No data
There are no items to display.
No vendors on your watchlist yet
Add vendors you want to track. You will see their status, insurance, and recent jobs here.
Add a vendor"No data" treats the user as a database. The right version names what would be here, why it matters, and gives the first action.
Search returned nothing
No results found
Your search did not match any records.
Nothing matched "acme corp"
Try a shorter query, check the spelling, or clear filters to see all vendors.
Clear filtersThe right version echoes the query so the user knows the search ran, names two concrete ways to broaden it, and offers the escape hatch.
Empty states are where Voice & Tone meets product context. Four rules carry most of the weight.
The headline says what kind of content the surface holds. "No vendors yet" works because the user knows what a vendor is in this app. "No data" works for nobody.
Explain what the surface is for in one or two sentences. Skip apologies, marketing language, and motivational filler.
"Add a vendor" beats "Get started." Lead with the object the user is working with. For no-results, "Clear filters" beats "Reset."
A failed filter is not a user error. "Nothing matched" beats "Your search returned no results." Stay neutral and offer the path forward.
Empty states are heard as well as seen. The icon is decorative; the structure carries the meaning.
The headline is a real heading at the right level for the surrounding page, usually H2 or H3. Do not use a styled paragraph and skip the semantic.
The icon or illustration carries no information by itself. Use aria-hidden so screen readers skip it; the headline and body must stand alone.
When an empty state replaces a populated view, the primary action should be the next focusable element after the surface heading. Do not force focus into the empty state on render.
For no-results after search or filtering, announce the changed result state with a polite live region. Do not use role="alert" unless the absence is urgent.
The pattern composes existing primitives. A coding agent should reuse the system pieces below before introducing anything new.
For surfaces that already use Panel, keep the empty state inside the same panel. For full-page empties, no extra panel is needed because the page layout already provides the frame.
Primitives: Panel
Use stack, inset, and section-gap tokens for vertical rhythm. Do not hardcode pixel values to center the surface.
Use this as the acceptance gate before approving an empty state in product work.
