# Empty-state messages

> Empty-state messages guide users, reduce confusion, and encourage meaningful action. Rather than leaving screens blank, they provide contextual messaging and clear next steps.

## Best practice template

We follow this three-step approach when creating our empty-state messages. They explain why data is missing, suggest how to populate it, or offer links to relevant tools and documentation. Although not every empty-state message in a product requires all three steps, aim for this whenever possible.

| Step | Purpose      | Description                                                                                                                 | Example                                                               |
| :--- | :----------- | :-------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| 1.   | Heading      | Explain this is empty intentionally and should be there, i.e. this empty space is not an error.                             | No projects added                                                     |
| 2.   | Description  | Give a clear reason why this space is empty. Provide context to help users understand the purpose of the empty-state space. | To display projects here, first add a project from your Project list. |
| 3.   | Instructions | Explain how users can fill the space by adding links, buttons and suggestions to move the user forward.                     | Add projects                                                          |

## General rules

Use the template when the error stops users moving forward.

  
    
      Heading: No zones added
      Description: Add zones to your profile to see them listed here.
      Button: Add zones
    
  

  
    
      Heading: No zones created
      Description: Add region from your dashboard.
      Button: Make sectors
    
  

Use clear action verbs to show users how to fill the empty state.

  
    
      Heading: No users added 
      Description: Add users in User management.
      Button: Open User management
    
  

Use neutral framing of the empty state and avoid making it seem like a user failure.

  
    No users added
  

  
    You haven’t added any of your users
  

Avoid “yet” or other expectation-related terms in headings.

  
    Heading: No users added
  

  
    Heading: No users added yet
  

## Dos and Don’ts

  
    
      Do make all messages consistent in terms of grammar and punctuation
      Do make sure users understand the space is not an error or a bug
      Do provide an option to fill the empty space with a button or link
    
  
  
    
      Don’t overcommunicate about the function of the empty state
    
  

## Related

- [Icon usage](../../../icons/icon-usage.mdx)
- [Error messages](./error-messages.mdx)
- [Warning messages](./warning-messages.mdx)
- [Non-critical information messages](./non-critical-information-messages.mdx)