--- schema_version: "1" id: 472c216e532d449cc059c751cebfda24f1355b80308b139887cb484b8ae6aca7 title: Illustration (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/illustration/lightning-illustration.md canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-illustration.html source_site: developer.salesforce.com content_type: documentation content_hash: 0deb529cde4ebe7c1f572bcb45a6d0a540b1e65d785eb5bf35d356b629816d0e products: - Lightning Component Reference --- # Illustration (Beta) **`lightning-illustration`** Displays a Salesforce Lightning Design System illustration. **For Use In** Lightning Experience, Experience Builder Sites ::::::tabset{tabs='["Develop", "Specifications"]'} :::::tab **note:** `lightning-illustration` 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-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. | Feature | Developer Benefit | | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Automatic Design System Compliance | Ensures uniform illustrations, eliminating manual checks for adherence to design guidelines. | | Simplified Updates | Reduces the effort of updating illustrations by enabling centralized management with the component. A change to the illustration propagates everywhere you use the component. | | Dynamic Theme Support | Illustrations dynamically adapt to themes, supporting light and dark mode and themes based on SLDS 1 and SLDS 2. | ## Design `lightning-illustration` implements the [Illustration blueprint](https://www.lightningdesignsystem.com/2e1ef8501/p/759a28-illustrations) 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. | | SLDS 1 | SLDS 2 | | :------------- | :---------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | | **Design** | [Illustration](https://v1.lightningdesignsystem.com/components/illustration/) | [Illustration](https://www.lightningdesignsystem.com/2e1ef8501/p/759a28-illustrations) | | **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-empty-state` 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`](/docs/platform/lightning-component-reference/guide/lightning-empty-state.html) where you don’t require the supporting text or call-to-action content. ## Usage 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. ```html ``` ## Specify Illustration Names 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. ### Illustrations for SLDS 2 and SLDS 1 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"`. ![Rain cloud illustration for error:unrecoverable ](https://developer.salesforce.com/media/raincloud.png) In an SLDS 1 theme, the same `illustration-name="error:unrecoverable"` attribute causes the component to display an illustration of a closed walking trail. ![Closed trail illustration for error:unrecoverable](https://developer.salesforce.com/media/nowalkthrough.png) 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. ![Gone fishing illustration used as a fallback](https://developer.salesforce.com/media/gonefishing.png) ### Map of Illustration Names to Illustrations for SLDS 2 and SLDS 1 These illustration names in `category:name` format are available. Visit the [Illustration component design](https://www.lightningdesignsystem.com/2e1ef8501/p/759a28-illustrations) 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. | 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 | ## Size and Spacing `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. ```html
``` ## Usage Considerations 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](https://www.lightningdesignsystem.com/2e1ef8501/p/05098e-utility-classes). Don’t embed text in the SVG. ## Accessibility `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. ::::: :::::tab ::component-specification{component="illustration" model="lwc" namespace="lightning"} ::::: ::::::