Empty state

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

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.

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.

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 case	Sample content format	CTA	Illustration
A user needs to create something to populate the empty state	No [items] yet To get started [doing task], create [item].	Create [item]
The system populates the empty state once the user does something	No [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 case	Sample content format	CTA	Illustration
A user ran a search/filter and no results matched the criteria	No [thing] matched your search Try [action].
A user is waiting on the system to populate something	No [thing] yet You'll see [thing] here when [something happens].
A user is waiting for access/permissions	Your 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 page	No 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 case	Sample content format	CTA	Illustration
Something went wrong with the system	We could not load [thing] Try reloading the page.	Reload page (optional)
User doesn’t have access or permissions	No [thing] yet You'll see [thing] here when [something happens].
404 page	Page 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.

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.

• Figma

If you're interested in contributing more guidelines, please reach out in a GitHub Discussion.