Anatomy
- Illustration: (Optional) A visual element that supports the message of the empty state.
- Title: A concise explanation of the feature or the reason for the empty state.
- Description: Additional context to help users understand the situation.
- Actions: (Optional) Clear next steps or options for the user to take.
Usage Guidelines
When to use this component
First-time use of a feature that depends on data
Use an empty state to introduce features that require user input or data before anything is displayed, and guide users on how to get started.
Empty search or filter results
Show an empty state when searches or filters return no results, explaining the situation and suggesting possible next steps.
Failure and success states resulting in no data
Present an empty state after an action (such as clearing all notifications) to reassure the user that everything is up to date and there is nothing left to review.
When not to use this component
Temporary feedback messages
Don’t use empty states for feedback that should be presented as a temporary toast or notification.
Best Practices
Always provide a clear next step with a primary button.
Don’t use system icons as visuals instead of illustrations.
If you need to explain the feature further and that requires navigation, place a link below the button/s.
Avoid using illustration if the space is scarce.
General Component Behaviors
Texts truncation
Title: can have a maximum of 2 lines, and the text will be truncated with ellipsis when it reaches the limit.
Description: can have a maximum of 4 lines (recommended to use less), and the text will be truncated with ellipsis when it reaches the limit.
Illustration
For the correct and balanced use of illustrations, we recommend using only the following sizes:
- Medium (default): Use when the empty state is the only content on the screen (e.g., a "First Run" experience or a screen like "Tasks").
- Small: Use when the empty state appears within a shared layout, such as a bottom sheet.
- XSmall: Use where vertical space is at a premium
Action Variants
Depending on the intent of the message and the required path to resolution, use one of the following action variants:
- Primary button: The default choice for the most important path to resolution. Use this to encourage the user to create data (e.g., "Create new episode")
- Primary + Link: Used when a main action is required, but a secondary, lower-priority option, such as "Learn more", is needed to provide additional context or help.
- Primary + Secondary: Best for scenarios where the user has two distinct paths of similar importance, though the Primary button should always highlight the most common next step. (e.g. “Import patients” + “Add a patient”)
- Link only: A subtle, low-emphasis variant for non-critical navigation or actions that are secondary to the overall user flow.
- No actions: Used for informative or "success" states where no immediate user input is required (e.g., "There are no new notifications").
Content Guidelines
- Aim for a short, clear title — use just a few words. Let the user know exactly why there is no content. Do not use a full stop or exclamation mark at the end of the title. 1 line of text is recommended.
- Provide additional context or guidance as the description. 1-2 lines is perfect. Always end the description with a full stop to signify a complete thought.
- Avoid blaming the user or using negative language.
- Always provide a path forward (e.g, with an action), unless empty state is the desired end state.
For further information, see the Content Styleguide.