> ## Documentation Index
> Fetch the complete documentation index at: https://content-designer-ux-writing-skill-26.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing empty states

> Guide users when content is absent with helpful empty state copy

Empty states appear when there's no content to display. Good empty state copy transforms a potentially confusing moment into an opportunity to guide users forward.

## Types of empty states

<Tabs>
  <Tab title="First-use">
    ### First-use empty states

    When users haven't created any content yet.

    **Purpose**: Welcome users and guide them to their first action

    **Pattern**: `[What this space is for]. [CTA to get started].`

    **Examples**:

    * "No projects yet. Create your first project to get started."
    * "Your task list is empty. Add a task to begin."
    * "No messages yet. Start a conversation to connect with your team."

    <Tip>
      Use encouraging language. "Yet" implies content will appear soon and makes the empty state feel temporary.
    </Tip>
  </Tab>

  <Tab title="User-cleared">
    ### User-cleared empty states

    When users have deleted or completed all content.

    **Purpose**: Acknowledge the cleared state and offer next actions

    **Pattern**: `[Acknowledgment]. [Optional CTA].`

    **Examples**:

    * "All done! No tasks remaining."
    * "Inbox zero. You've read all your messages."
    * "Archive is empty."

    <Note>
      User-cleared states can be more celebratory. Users achieved this state intentionally.
    </Note>
  </Tab>

  <Tab title="Error/No results">
    ### Error or no results

    When a search or filter returns nothing, or content failed to load.

    **Purpose**: Explain why there's no content and suggest recovery

    **Pattern**: `[No results]. [Suggestion to adjust].`

    **Examples**:

    * "No results found. Try a different search term."
    * "No projects match these filters. Clear filters to see all projects."
    * "Couldn't load messages. Check your connection and refresh."

    <Warning>
      Don't leave users in a dead end. Always provide a way to recover or adjust.
    </Warning>
  </Tab>
</Tabs>

## The formula

```
[Explanation] + [Call to action]
```

Every empty state should:

1. Explain why it's empty
2. Tell users what to do next

## Format guidelines

<Steps>
  <Step title="Start with the state">
    Lead with what's empty or missing.

    * **Good**: "No data yet."
    * **Avoid**: "It looks like you haven't added any data."
  </Step>

  <Step title="Keep it concise">
    Empty states should be scannable (under 15 words ideal).

    * **Good**: "No tasks yet. Create a task to get started."
    * **Avoid**: "You don't have any tasks in your list right now. To get started, you can create a new task by clicking the button below."
  </Step>

  <Step title="Include a clear CTA">
    Tell users exactly what action to take.

    * **Good**: "Connect your account to see insights."
    * **Avoid**: "Get started to see your data here."
  </Step>

  <Step title="Use encouraging tone">
    Make the empty state feel temporary and achievable.

    * **Good**: "No integrations yet. Add your first integration."
    * **Avoid**: "You have no integrations."
  </Step>
</Steps>

## Examples by context

### SaaS dashboards

<Accordion title="Analytics dashboard">
  **State**: User hasn't connected a data source

  **Empty state**: "No data yet. Connect your account to see insights."

  **Why it works**:

  * "Yet" implies this is temporary
  * Clear action (connect account)
  * Explains benefit (see insights)
</Accordion>

<Accordion title="Team workspace">
  **State**: No team members invited

  **Empty state**: "Just you so far. Invite teammates to collaborate."

  **Why it works**:

  * Friendly tone ("just you so far")
  * Clear CTA (invite teammates)
  * States benefit (collaborate)
</Accordion>

### Content lists

<Accordion title="Document library">
  **State**: No documents uploaded

  **Empty state**: "No documents yet. Upload your first file."

  **Why it works**:

  * Simple and direct
  * Clear first action
  * Under 10 words
</Accordion>

<Accordion title="Completed all todos">
  **State**: User cleared their task list

  **Empty state**: "All done! No tasks remaining."

  **Why it works**:

  * Celebrates achievement
  * Acknowledges cleared state
  * No pressure to create more tasks
</Accordion>

### Search and filters

<Accordion title="No search results">
  **State**: Search returned no matches

  **Empty state**: "No results for 'keyword'. Try a different search term."

  **Why it works**:

  * Shows what they searched for
  * Suggests concrete action
  * Not a dead end
</Accordion>

<Accordion title="Filter too restrictive">
  **State**: Filters exclude all content

  **Empty state**: "No items match these filters. Clear filters to see all items."

  **Why it works**:

  * Explains why it's empty
  * Provides recovery action
  * Specific about solution
</Accordion>

## Visual pairing

Empty states often include visual elements:

<CardGroup cols={2}>
  <Card title="Simple icon" icon="inbox">
    For routine empty states, a simple icon reinforces the message without adding noise.
  </Card>

  <Card title="Illustration" icon="image">
    For onboarding or first-use states, a welcoming illustration can reduce anxiety.
  </Card>
</CardGroup>

<Note>
  Visual elements should support the message, not replace it. Always include text.
</Note>

## Common mistakes

<Warning>
  Avoid these patterns that frustrate users:
</Warning>

* **Robotic language**: "No data available" → "No data yet. Connect your account."
* **Dead ends**: "Nothing here" → "No messages yet. Start a conversation."
* **Blame language**: "You haven't created any projects" → "No projects yet. Create your first project."
* **Overly clever copy**: "Looks like tumbleweeds around here" → "No activity yet. Create a post."
* **Too much text**: Long explanations → Brief explanation + CTA

## Before and after examples

### Example 1: Dashboard

| Before                                          | After                                                 | Why it's better           |
| ----------------------------------------------- | ----------------------------------------------------- | ------------------------- |
| "No data available."                            | "No data yet. Connect your account to see insights."  | Adds CTA and benefit      |
| "There is currently no information to display." | "No analytics yet. Add tracking code to get started." | Concise + specific action |

### Example 2: Lists

| Before                            | After                                                  | Why it's better                   |
| --------------------------------- | ------------------------------------------------------ | --------------------------------- |
| "You don't have any saved items." | "No saved items yet. Save an item to access it later." | Removes "you" blame, adds purpose |
| "Empty"                           | "No files yet. Upload a file to get started."          | Explains and guides               |

### Example 3: Search

| Before                              | After                                                         | Why it's better                     |
| ----------------------------------- | ------------------------------------------------------------- | ----------------------------------- |
| "0 results"                         | "No results found. Try a different search term."              | Adds recovery action                |
| "Sorry, we couldn't find anything." | "No matches for 'keyword'. Adjust your search and try again." | Shows search term + concrete action |

## Accessibility

<Check>Don't rely solely on illustrations - always include text</Check>
<Check>Make CTAs keyboard accessible</Check>
<Check>Use semantic headings to structure empty state content</Check>
<Check>Ensure illustrations have alt text if they convey meaning</Check>

## Quick checklist

Before shipping an empty state:

* [ ] Explains why it's empty
* [ ] Provides clear next action
* [ ] Uses encouraging tone ("yet" for first-use)
* [ ] Under 15 words
* [ ] Includes actionable CTA
* [ ] Avoids blame language
* [ ] Works without visuals

## Related resources

<CardGroup cols={3}>
  <Card title="Templates" icon="file-lines" href="/reference/templates">
    Use the empty state template
  </Card>

  <Card title="Voice and tone" icon="comments" href="/concepts/voice-and-tone">
    Match tone to your brand
  </Card>

  <Card title="Examples" icon="lightbulb" href="/reference/examples">
    See real-world improvements
  </Card>
</CardGroup>