---
schema_version: "1"
id: 8db94dd91aca77079ff6d0fc8022e0deaa27198184f4500b39399ecdc78eb098
title: Empty State (Beta)
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/emptyState/lightning-empty-state.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-empty-state.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 04a7c687e0ef49a4eef778faf0c8176ae3177349cb9eaeb86164c816fcaf0e9a
products:
- Lightning Component Reference
---
# 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
::::::tabset{tabs='["Develop", "Specifications"]'}
:::::tab
**note:** `lightning-empty-state` is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.
The `lightning-empty-state` component shows 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 show 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. |
## Design
`lightning-empty-state` implements the illustration (empty state) blueprint in the Salesforce Lightning Design System (SLDS). The empty state adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.
| | SLDS 1 | SLDS 2 |
| :------------- | :-------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design** | [Illustration (Empty State)](https://v1.lightningdesignsystem.com/components/illustration/#Using-Empty-States/) | [Empty State](https://www.lightningdesignsystem.com/2e1ef8501/p/09f001-empty-state) |
| **For Use In** | Lightning Experience, Experience Builder Sites | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |
## Compare to `lightning-illustration`
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 show text to help users understand why a container has no items to show. 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`](/docs/platform/lightning-component-reference/guide/lightning-illustration.html) 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.
## Usage
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 `` 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 `
` element.
Here’s an example that uses `lightning-empty-state` with a title and description, but not an illustration.
```html
Try adjusting your search criteria.
```
## Present 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 shows an empty state of a customer’s cart before the customer has placed items in it, specify `illustration-name="cart:noitems"` to show an illustration of an empty shopping bag.
```html
Add items to get started.
```
### Illustrations for SLDS 2 and SLDS 1
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.
### Map of Illustration Names to Illustrations for SLDS 2 and SLDS 1
These illustration names are available. Visit [Empty State component design](https://www.lightningdesignsystem.com/2e1ef8501/p/09f001-empty-state) 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).
```html
When you add items to your cart, they’ll appear here.
```
SLDS 2 themes show the empty shopping bag image for the `cart:noitems` illustration.
![Empty bag illustration for cart:noitems in Salesforce Cosmos theme](https://developer.salesforce.com/media/no-items.png '{"class": "image-sm", "title": "Salesforce Cosmos"}')
SLDS 1 themes show the gone fishing image for the `cart:noitems` illustration.
![Gone fishing illustration for cart:noitems in Lightning Blue theme](https://developer.salesforce.com/media/gonefishing.png '{"class": "image-sm", "title": "Lightning Blue"}')
## Override the Responsive Illustration Size
`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`.
| 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 | `x-small` | No illustration is shown |
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.
```html
Try adjusting your search criteria.
```
## Add an Action Button to the 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.
### Use an Illustration and an Action Button
This example shows an empty cart illustration along with a **Browse Products** call-to-action button with the brand variant.
```html
Add items to get started.
```
```javascript
import { LightningElement } from "lwc";
export default class MyEmptyState extends LightningElement {
handleCtaClick(event) {
// go to the Shop tab
}
}
```
### Use CTA Slot on a Container
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.
```html
Please try again.
```
## Usage Considerations
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.
## Accessibility
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](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button.html?type=Develop#accessibility) for more information about accessibility support for buttons.
:::::
:::::tab
::component-specification{component="emptyState" model="lwc" namespace="lightning"}
:::::
::::::