Skip to contentSkip to navigationSkip to topbar
Figma
Star

Empty state

The Empty State pattern provides the user with guidance on what steps to take if content is either unavailable or cannot be displayed.

Product
Console
Flex
SendGrid
Segment

Ingredients

Ingredients page anchor

Card

For Card sizing, go to the Sizing & responsiveness section for more details.

For illustrations, we recommend using a fixed width of $size-20. The illustration must be directly related to the message you’re communicating. Read more about which illustrations to use for each use case.

// import all ingredients for the empty state patterns
import {​Card} from "@twilio-paste/core/card";
import {Heading} from "@twilio-paste/core/heading";
import {Paragraph} from "@twilio-paste/core/paragraph";
import {Button} from "@twilio-paste/core/button";
import {​Anchor} from "@twilio-paste/core/anchor";

General

General page anchor

Use an empty state to explain to a customer why content is unavailable or can't be displayed. Empty states can appear anywhere you display content, and are a good opportunity to improve customer comprehension.

An empty state should:

  • Be clear: If there's a path forward, explain it as concisely as possible. Include an explanation for why a customer is seeing the empty state if it helps them better understand what to do next.
  • Give direction and educate the customer: Let customers know what steps they can take to move forward. Guiding them to "Create an alpha sender" is more helpful than saying "No alpha senders".
  • Be encouraging and inspire confidence: Use a friendly and approachable tone to ensure a positive experience. Never make customers feel unsuccessful or guilty because they're seeing an empty state. Even when they arrive at a page "in error" (for example, on a page they don't have permissions to), encouraging messaging and an explanation of possible solutions can give customers confidence that they're heading in the right direction.

In most cases, an empty state has a Heading, a Paragraph, and a call to action. Sometimes, an empty state has an illustration.

Heading

Heading page anchor

The Heading should be concise and convey the main takeaway. Use only a heading if there is no additional context to provide.

The Paragraph should provide additional context or information. Describe what the user can do next and the benefit to the user. If there is no more information to convey, omit this component.

The CTA should appear within the empty state, unless the CTA is already on the page when it loads. A CTA separate from the rest of the empty state could draw the user’s attention away from their primary goal.

When there’s no immediate action to be taken, consider making the CTA a way to get back to a previous screen or start a related workflow. This approach is useful when the user is waiting for data to process or for an approval.

Occasionally, CTAs aren’t necessary. For example, if the empty state is a preview pane and is dependent on the user taking action elsewhere on the page.

Use an illustration only if it’s directly related to the message you’re communicating. Overusing illustrations can minimize their emotional and visual impact. Learn more about requesting a new illustration.

When an empty state card is wider than 540px (recommended), use padding="space150", and align illustrations horizontally with the text content.

In smaller spaces, use padding="space100" and stack the illustration in the card above the text content.

If your empty state composition needs to accommodate different screen sizes, you can also wrap it in the Stack or Grid component.

(information)

If you'd like to contribute guidelines for the empty state pattern in even more compact situations, like a navigation panel or components like Combobox, please reach out in a GitHub Discussion!

Open the sandbox in a new tab and resize the browser for an example of responsive sizing.

For call-to-actions in an empty state, use an Anchor if the action will take the user to a new URL. In all other cases, use a Button. For detailed guidance on applying this recommendation, check out the Button vs. Anchor pattern.

These empty states occur during the user’s first interaction with a feature and are an opportunity to educate the user. The content should indicate what the user can expect to see once the area is populated, address the benefit or motivation for taking action, and guide the user to get started. When appropriate, consider opportunities for launching an onboarding flow, in-depth education detail to drive engagement, or starter content like templates.

Use caseSample content formatCTAIllustration
A user needs to create something to populate the empty stateNo [items] yet
To get started [doing task], create [item].
Create [item]
The system populates the empty state once the user does somethingNo [thing] yet
You haven't [taken an action]. [Take an action], then track [things] here.
[Take an action] (optional)

A no data empty state can occur when:

  • A search or filter yields no results.
  • A user has cleared the data.
  • A user must wait for data to populate.
  • A user is waiting for permission/access.

When data is absent due to search parameters, the content should communicate why there is no data and explain what the user could change to populate results.

When data is absent due to a user waiting for data to populate, consider a CTA leading them back to a previous screen or suggesting a related task.

Use caseSample content formatCTAIllustration
A user ran a search/filter and no results matched the criteriaNo [thing] matched your search
Try [action].
A user is waiting on the system to populate somethingNo [thing] yet
You'll see [thing] here when [something happens].
A user is waiting for access/permissionsYour request was submitted
You'll see [thing] here when your request is approved.
Go back to [page] (optional)
A user cleared all the data (like alerts or notifications)No new [things]
To review previous [things], go to [page].
Go to [page] (optional)
A preview is populated after the user inputs info elsewhere on the pageNo preview yet
To see what your [thing] will look like, [do a task].
Do task (optional)(optional)

Error empty states can result from problems like a system issue or access issue. The content should explain what went wrong and tell the user how to fix the issue. Consider including an error icon to complement the content. If the error empty state occurs in a small component (a card, for example), prioritize communicating how to fix the problem. For error message guidance, review the error state pattern.

Use caseSample content formatCTAIllustration
Something went wrong with the systemWe could not load [thing]
Try reloading the page.
Reload page (optional)
User doesn’t have access or permissionsNo [thing] yet
You'll see [thing] here when [something happens].
404 pagePage not found
The page you're looking for either doesn't exist or was moved.
Go back

Use a cross-sell or upsell empty state on pages that give access to parts of a product that need to be purchased by the customer.

Focus the headline on the overall user benefit, with supplemental text providing additional content on the ‘how’.

Cross-sell and upsell empty states almost always include a CTA to contact Sales and an illustration.

When an empty state appears in a situation with limited space, like a Combobox, confine the empty state to a single sentence using the Paragraph component.

For empty states that are eventually replaced by visual components like a chart or graph, consider including information that shows users what the eventual chart or graph would look like. For example, you could include the labels for the x- and y-axes or a muted graphic that shows the type of chart.

Multiple empty states on a page

Multiple empty states on a page page anchor

When a page has multiple pieces populated by different data sources, it’s possible to have several empty states at once. Generally, each piece should have its own empty state since they show different types of data and may require unique CTAs.

A possible exception to this is the case where all pieces of the page are simultaneously in an error state. If possible, it is less distracting and distressing to show a single error state for the page than an error state for each piece of the page.

Do

Include a heading that summarizes the situation.

Don't

Don't include too many details in a heading. A heading shouldn't be more than 2 lines.

Do

Do use a period in supplemental text.

Don't

Don't use a period at the end of a heading.

Do

Include a more detailed explanation of the situation and next steps, when applicable.

Don't

Don't repeat the heading copy in supplemental text.

Do

Show a CTA within the empty state.

Don't

Avoid showing the same CTA twice on a page.

Do

Limit CTAs to 1 or 2.

Don't

If 3 or more CTAs are needed, consider grouping them under different headings or other content sections.

Do

Use an illustration that's directly related to the message you are sending.

Don't

Don't use a random illustration.

If you're interested in contributing more guidelines, please reach out in a GitHub Discussion(link takes you to an external page).