Skip to content
Paste
UX Platform
GitHub

Empty states

Give customers guidance on what steps to take if content is either unavailable or can't be displayed.

Status
beta

Ingredients#

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';

Usage#

General#

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

Empty states 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.

Accessibility#

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.

Variations#

Empty state with an immediate next step#

In most cases, empty states have a Heading summarizing 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#

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.

Sizing & Responsiveness#

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.

If you'd like to contribute guidelines for empty states 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#

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"Create an object illustrationDownload 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"No results found illustrationDownload 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.Awaiting data illustrationDownload from the Brand library
Generic dependency stateThe customer needs to do something or go somewhere else to continue their workflow.Generic dependency state illustrationDownload from the Brand library
No permissions to viewThe customer doesn't have permissions to view the page."Request access to WhatsApp"No permissions to view illustrationDownload 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"Change regional data location illustrationDownload from the Brand library

Dos and Don'ts#

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.

Starter kits#

Figma#

Coming soon

What's missing?#

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

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

Black lives matter.