Empty State (Beta)
lightning-empty-state
Presents information to help users understand why a panel or other container has no content.
For Use In
Lightning Experience, Experience Builder Sites
lightning-empty-state is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.
The lightning-empty-state component displays content that represents an "empty state" of a container, such as a panel or card, in which your users expect data to appear. Empty states tell users why there’s no content to display and can guide them to what they can do next.
For example, an empty state can reflect these common conditions.
- An error prevents content loading
- The system is undergoing maintenance
- A search or filter returned no results
- A shopping cart is empty
- A user cleared a list of items
The lightning-empty-state component provides a standardized solution for depicting empty states. Instead of creating custom layouts, styling, and illustration handling, use lightning-empty-state to take advantage of these benefits.
| Feature | Developer Benefit |
|---|---|
| Consistency | Ensures uniform empty state patterns across the platform with automatic design system compliance. |
| Simplified Development | Provides a ready-to-use component that eliminates the need for custom empty state implementations. |
| Dynamic Theme Support | Illustrations dynamically adapt to themes, supporting light and dark mode and themes based on SLDS 1 and SLDS 2. |
| Responsive Design | Built-in responsive behavior that adapts to different container sizes. |
The lightning-empty-state component implements the Empty State design from Salesforce Lightning Design System 2 (SLDS 2).
The lightning-empty-state component uses the lightning-illustration component internally to present scalable vector graphics (SVG) illustrations. Both the lightning-empty-state and lightning-illustration components currently support the same sets of Salesforce SVG illustrations for depicting empty state conditions.
Use the lightning-empty-state component to display text to help users understand why a container has no items to display. Optional call-to-action (CTA) controls and content can help users react, and an optional illustration can help to reassure users.
Currently, you can use lightning-illustration for similar use cases as lightning-empty-state where you don’t require the supporting text or call-to-action content. More illustrations are in development for other use cases.
Use the lightning-empty-state component to present informative text and an optional decorative illustration when a container doesn't display content. The component provides a friendly and consistent way to help your users understand why there's no content. You can also add a button to help them take the next action.
The only required content for lightning-empty-state is the description slot. Use the description slot to explain the empty state scenario and, if possible, guide users to the next activity. The description slot gives you flexibility in presenting the information. For example, you can use a simple <p> element, which we recommend. If your use case calls for it, you can use multiple paragraphs or another element such as an unordered list.
Provide an optional title attribute to create a heading that gets attention and tells users what’s happening. Depending on the use case of the empty state notice, titles can be playful, or more direct and terse. The component renders the title in a <h3> element.
Here’s an example that uses lightning-empty-state with a title and description, but not an illustration.
Specify the optional illustration-name attribute to include an SLDS illustration in the empty state component. The component automatically detects the SLDS version of the theme that’s enabled in Salesforce. This detection enables the component to present different illustrations for SLDS 2 and SLDS 1 themes. In SLDS 2 themes, the illustrations also adapt automatically for dark mode and theme and branding that’s in effect in the org.
illustration-name accepts a name in the format set:symbol (which you can think of as category:name) to retrieve an SVG image from SLDS. For example, if your component displays an empty state of a customer’s cart before the customer has placed items in it, specify illustration-name="cart:noitems" to display an illustration of an empty shopping bag.
The lightning-empty-state component displays a unique SVG image for each illustration that you can specify with the illustration-name attribute. The illustration name follows the category:name pattern, for example, cart:noitems and error:connectionissue.
For SLDS 2 themes, lightning-empty-state uses new Salesforce Cosmos illustrations. For SLDS 1 themes, the component uses a smaller set of existing SLDS 1 illustrations from Lightning Experience.
Each of the SLDS 1 illustrations maps to one of the same category:name illustration names. The mapping enables lightning-empty-state to work in SLDS 1 themes. However, some SLDS 1 illustrations map to multiple illustration names. This reuse of illustrations means that SLDS 1 themes don't have a unique SVG image for each illustration name.
These illustration names are available. Visit Empty State component design to see the current images and their use cases. This table describes the images that map to the illustration names to aid you in recalling the images. You can avoid looking them up in the design each time.
| Illustration Name | SLDS 2 | SLDS 1 |
|---|---|---|
access:deleted | A cocoon or chrysalis | An open empty treasure chest |
access:limit | An extinguished candle | A closed treasure chest |
access:request | A locked padlock | A closed treasure chest |
cart:noitems | An empty shopping bag | Gone fishing - Astro and Codey in a canoe |
error:appconnection | A stylized balloon | Floating hot air balloons |
error:connectionissue | An unplugged electrical plug | Floating hot air balloons |
error:recoverable | A wilting plant | A rainy campsite |
error:unrecoverable | A rain cloud | A walking path that's closed |
maintenance:planned | A healthy plant | A hand under a landscape |
maintenance:unplanned | A boomerang | A hand under a landscape |
noresults:filter | Three plants, the tallest bending to the sun | Binoculars with a cracked lens |
noresults:search | A telescope pointing away from the sky | Binoculars with a cracked lens |
noresults:unknown | Mountains and clouds | Binoculars with a cracked lens |
success:assigned | Umbrella planted on a beach | Gone fishing - Astro and Codey in a canoe |
success:new | A zen sand garden | Gone fishing - Astro and Codey in a canoe |
success:selfassigned | A flag planted on a hill | Gone fishing - Astro and Codey in a canoe |
For example, this component automatically shows different illustrations for SLDS 2 themes (an empty shopping bag), and SLDS 1 themes (a “gone fishing” scene).
SLDS 2 themes show the empty shopping bag image for the cart:noitems illustration.
SLDS 1 themes show the gone fishing image for the cart:noitems illustration.
lightning-empty-state adapts automatically to the container that it's in, scaling the size of text and illustrations. By default, the component performs responsive sizing by querying the size of the container before setting an illustration size. Based on the size of the container, the component sets one of three sizes: medium, small, and xsmall.
| Container Type | Container Width | Illustration Size | Illustration Width |
|---|---|---|---|
| Full page or large panel | 366 px or more | medium | 304 px |
| Card | 256–365 px | small | 184 px |
| Mobile device, small card, nested panels | 0–255 px | xsmall | No illustration is shown |
To override the automatic sizing, you can specify the size attribute with a value of medium, small, or xsmall. For example, to make the empty state component render an illustration as small even when it’s in a large panel, set size="small". If you set size to xsmall, any illustration you specify doesn't appear.
This example sets the size to small.
The component provides a slot called cta for a call-to-action button. Use lightning-button with slot="cta" to give users a recommended action to perform when presented with an empty state. Use the brand variant to draw attention to the recommended action.
This example shows an empty cart illustration along with a Browse Products call-to-action button with the brand variant.
For multiple buttons in a call-to-action, use the cta slot on a container element. Use no more than two buttons. If you use two buttons, use the brand variant for the primary action button and the neutral variant for the other button.
The lightning-empty-state component works only on the Salesforce platform. It requires access to the SVG illustrations in a Salesforce org.
The component works in Experience Builder Sites, but can only display SLDS 1 illustrations. SLDS 2 isn't supported in Experience Cloud.
This component uses new Salesforce Cosmos illustrations to fit the SLDS 2 themes. Develop with the SLDS 2 version of the illustration in mind first, and then test the component with SLDS 1 themes.
The lightning-empty-state component has an optional alternative-text attribute for specifying text for assistive technologies. Use alternative-text if the illustration conveys meaningful information such as why no results appear. Use concise, purposeful text such as "No search results." Omit alternative-text if the illustration is purely decorative and the title or description communicates the message.
The title renders as an h3 element. If you use lightning-empty-state in a location where a level 3 heading isn’t hierarchically accurate for assistive technologies, use the heading-level attribute to set the level appropriately. Valid heading-level values are 1, 2, 3, 4, 5, and 6.
The illustrations support SLDS standards for high color contrast across all themes.
The call-to-action button is the only interactive element. Use keyboard navigation to get to the call-to-action button, and press Enter or the spacebar to select.
See the lightning-button documentation for more information about accessibility support for buttons.