Skip to content
Change the site theme
(information)

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

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

This pattern is used to explain to a customer what they should do next if content is either unavailable or can't be displayed.

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, treat an empty state as an informational state of the entire page, and not a state that simply replaces a part of the page that should otherwise be populated. When you have text explaining what a page is for, try working it into the empty state card.

When a page is in an empty state, its call-to-action (CTA) should appear in the empty state card, not near the page heading like in the Create pattern. Exceptions can be made in cases like some "No results found" scenarios, when a CTA is already on the page on load. The visual focus of hiding the CTA that's outside of the card could draw too much of the customer's attention away from their primary goal.

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.

Empty state with an immediate next step

Empty state with an immediate next step page anchor

In most cases, an empty state has a Heading to summarize what's happening, a Paragraph that gives more detail to help a customer decide what to do next, and 1–2 calls-to-action.

Empty state requiring a customer to wait

Empty state requiring a customer to wait page anchor

A customer's next step might not always require an immediate call-to-action. Instead, the best path forward for them might be to wait for another process to complete and come back later. This happens most often when a customer is awaiting data through event logs, or when another person or non-Twilio service needs to approve a customer's request.

If the customer might need to start another workflow, consider giving them a way back to a dashboard or the start of another flow.

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 icon

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.

Examples of Empty State use cases

Examples of Empty State use cases page anchor

For all use cases:

  • Use a heading that succinctly summarizes the situation. We recommended a maximum of 7 words.
  • Use an illustration only if it’s directly related to the message you’re communicating. Don’t use a random illustration to “fill in the blank.” The more that illustrations are used throughout our products, the more they lose their emotional and visual impact when it really matters. Learn more about requesting a new illustration.
Use caseCustomer scenarioExample headingIllustration
Create an objectThe customer needs to create something new to populate the page or learn more about why/how to create it."Create an alpha sender"
Download from the Brand library
No results foundBased on a customer's search or filter criteria, we're unable to give them any results."No phone numbers found"
Download from the Brand library
Awaiting dataThe customer has done everything they need to do. Now they're waiting on a response or for data to come in.
Download from the Brand library
Generic dependency stateThe customer needs to do something or go somewhere else to continue their workflow.
Download from the Brand library
No permissions to viewThe customer doesn't have permissions to view the page."Request access to WhatsApp"
Download from the Brand library
Change regional data locationThe customer needs to swap regions to access the data."View event logs in the United States region"
Download from the Brand library
Do

Include a heading that summarizes the situation. We recommend a maximum of 7 words.

Don't

Don't include a long heading providing too many details. If the heading wraps to 2 or more lines, that may be a sign to be more concise. 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 paragraph text if it doesn't add additional clarity.

Do

Show a call-to-action in the empty state card only, unless the movement from hiding a CTA outside of the card draws too much of the customer's attention away from their primary goal.

Don't

Avoid showing the same CTA twice on a page.

Do

If the empty state requires CTAs, try to include no more than 2.

Don't

Avoid giving the user more than 3 calls-to-action on the same empty state, so they're not overwhelmed with choice. If more than 3 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. Check the list of illustrations to use based on use case.

Don't

Don't use a random illustration to "fill in the blank." The more that illustrations are used throughout our products, the more they lose their emotional and visual impact when it really matters.

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

Here are use cases we're know we're missing guidelines on:

Black lives matter.