Component contract
What it must accomplish
Turn absence into orientation, recovery, or a clear completion state.
First useNo resultsCompletedPermission-limitedUnavailable
Usage
Choose the control by behavior
Use it when
- A collection has no items
- Filters return no results
- Access, loading, or setup affects visibility
Use another pattern when
- The blank region is self-explanatory
- An error or loading state is the real condition
- Decorative content would distract from the next action
Anatomy
Stable parts create a reliable contract
- 1Concise heading
- 2Explanation
- 3Primary next action
- 4Optional secondary help or illustration
Explanation
Interaction and keyboard behavior
- Actions follow native behavior
- Focus remains at the initiating control for filtered-empty results
- Newly loaded content receives intentional, not automatic, focus
Why this matters
Visual similarity does not guarantee behavioral equivalence. The component contract must preserve state, focus, semantics, and recovery across input methods.
Cross-system baseline
Accessible behavior
- Differentiate empty, loading, and error states in text
- Preserve table or region labels
- Make recovery actions specific
- Do not use imagery as the only explanation
Responsive considerations
Adapt the decision—not only the dimensions
Keep the message close to the region it explains and avoid fixed heights that create giant blank surfaces.
Content considerations
Language is part of the component
- Name why content is absent
- Match the action to the cause
- Avoid blaming the user
Common mistakes
Patterns that weaken the experience
01
Showing raw NOT FOUND text
02
Using a giant placeholder
03
Offering Create when the person lacks permission
04
Treating filtered-empty as first use
Comparison
What to study across systems
Public-service systems often keep empty states restrained; product systems add onboarding or creation actions when they genuinely match the cause.
Open comparison