Empty State (Beta)

The lightning-empty-state component shows 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.

For example, this component automatically shows different illustrations for SLDS 2 themes (an empty shopping bag), and SLDS 1 themes (a “gone fishing” scene).

1<!-- With illustration  -->
2<lightning-empty-state illustration-name="cart:noitems" title="No items in cart">
3  <p slot="description">When you add items to your cart, they’ll appear here.</p>
4</lightning-empty-state>

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 x-small.

To override the automatic sizing, you can specify the size attribute with a value of medium, small, or x-small. 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 x-small, any illustration you specify doesn’t appear.

This example sets the size to small.

1<lightning-empty-state title="No results found" size="small">
2  <p slot="description">Try adjusting your search criteria.</p>
3</lightning-empty-state>

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.

1<!-- myEmptyState.html -->
2<!-- With illustration and action -->
3<lightning-empty-state illustration-name="cart:noitems" title="No items in cart">
4  <p slot="description">Add items to get started.</p>
5  <lightning-button variant="brand" label="Browse Products" slot="cta" onclick={handleCtaClick}>
6  </lightning-button>
7</lightning-empty-state>

1import { LightningElement } from "lwc";
2
3export default class MyEmptyState extends LightningElement {
4  handleCtaClick(event) {
5    // go to the Shop tab
6  }
7}

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.

1<lightning-empty-state title="Error occurred">
2  <p slot="description">Please try again.</p>
3  <div slot="cta">
4    <lightning-button variant="neutral" label="Cancel"> </lightning-button>
5    <lightning-button variant="brand" label="Retry"> </lightning-button>
6  </div>
7</lightning-empty-state>

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.