Illustration (Beta)

The lightning-illustration component displays Salesforce Lightning Design System (SLDS) scalable vector design (SVG) illustrations to communicate errors, success, and other statuses. This component provides access to a set of standardized SVG illustrations for use in the Salesforce platform.

The lightning-illustration component simplifies development and maintenance while ensuring a high-quality visual experience for your custom Lightning pages that’s consistent with the Salesforce platform.

lightning-illustration implements the Illustration blueprint in the Salesforce Lightning Design System (SLDS). The icons adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use. Consult the SLDS site for images of the available illustrations.

Both the lightning-illustration and lightning-empty-state components currently support only Salesforce SVG illustrations for depicting empty state conditions. The lightning-illustration component doesn’t currently support other standard illustrations or custom illustrations. The lightning-illustration component currently supports the same illustrations as lightning-empty-state.

To display an illustration that clarifies why a page or panel has no content, and provides text and call-to-action content, use the lightning-empty-state component.

Use lightning-illustration for similar use cases as lightning-empty-state where you don’t require the supporting text or call-to-action content.

The component is useful for displaying an illustration only, without any visible text. It supports only two attributes: illustration-name and alternative-text. The illustration-name is required.

Here’s a basic example.

1<lightning-illustration 
2  illustration-name="error:unrecoverable" 
3  alternative-text="Error occurred">
4</lightning-illustration>

The lightning-illustration component detects the SLDS version of the theme that’s enabled in Salesforce and presents different illustrations for SLDS 2 and SLDS 1 themes. In SLDS 2 themes, the illustrations also adapt automatically for dark mode and the theme and branding that’s in effect in the org.

illustration-name accepts a name in the pattern set:symbol (which you can think of as category:name) to retrieve an illustration from SLDS. For example, valid names include cart:noitems and error:connectionissue.

The lightning-illustration component displays a unique SVG image for each illustration that you specify with the illustration-name attribute.

For SLDS 2 themes, lightning-illustration presents 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-illustration 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.

For example, if your component encounters an error that isn’t fixable at the moment, specify illustration-name="error:unrecoverable".

In an SLDS 2 theme, the component displays an illustration of a rain cloud for illustration-name="error:unrecoverable".

In an SLDS 1 theme, the same illustration-name="error:unrecoverable" attribute causes the component to display an illustration of a closed walking trail.

The component automatically presents the illustration that’s appropriate for the theme.

If you pass an invalid illustration name, the component falls back to the “gone fishing” illustration in SLDS 1 themes. In SLDS 2 themes, there’s a console error.

These illustration names in category:name format are available. Visit the Illustration component design to see the current images. 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.

lightning-illustration automatically sizes to the full width of the container that it’s in. You can’t set the size directly in the component. To control the size, specify the container size. For example, wrap the component in a div and add a style to set the maximum width.

1<div style="max-width: 400px;">
2  <lightning-illustration
3    illustration-name="maintenance:planned"
4    alternative-text="Scheduled maintenance"
5  >
6  </lightning-illustration>
7</div>

The lightning-illustration component is supported 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.

Illustrations can clarify states like no data, success, access issues, or maintenance. Use lightning-illustration for more general status messaging, not for displaying in containers if there’s no data to display. Use lightning-empty-state for containers without data.

Render the illustration conditionally. For example, render an error illustration only in an error state.

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.

Choose an illustration that’s closest in meaning for your use case and provide messages in adjacent text components.

Rely on the component to detect the theme and handle switching between illustrations for SLDS 2 and SLDS 1. You can avoid branching your code.

Avoid changing illustration colors or shapes with custom CSS. Use layout and spacing utility classes.

Don’t embed text in the SVG.

lightning-illustration has an 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 surrounding UI communicates the message.

The illustrations support SLDS standards for high color contrast across all themes.