> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/illustration.md).

# Illustration

`avonni-illustration`

Displays an illustrated image alongside a title and message, typically for empty or error states.

## Overview

**Illustration** is a Lightning Web Component that displays a scenic SVG graphic with a title and optional supporting content, used to communicate empty, error, or informational states.

Use it in your own Lightning Web Components to fill empty lists, explain error conditions, or guide users when there's nothing to show. You pick the illustration art with the `variant` attribute, set a `title` and `size`, and add a message and actions through the default slot.

### Use Cases

* **Empty states:** Show a friendly graphic when a list or search has no results.
* **Error states:** Communicate connection or access problems with art and a retry action.
* **Onboarding:** Welcome users to a new feature with a setup illustration.
* **No access:** Indicate restricted content with the `no-access` variant.
* **Placeholders:** Fill empty regions of a custom page during loading or setup.

***

## Variant Guidelines

| Variant                | Use Case                              |
| ---------------------- | ------------------------------------- |
| `text-only`            | Title and message with no artwork.    |
| `no-connection`        | Offline or sync failure states.       |
| `no-access`            | Restricted or unauthorized content.   |
| `desert` / `open-road` | Generic empty states.                 |
| `setup`                | Onboarding and configuration prompts. |

***

## Use Case Examples

### Example 1: Error state with a retry action

**Scenario:** Show a connection-error illustration with a message and a retry button when data fails to load.

```html
<!-- errorState.html -->
<template>
    <avonni-illustration
        title="Something went wrong"
        variant="no-connection"
        size="large"
        alternative-text="Connection lost"
    >
        <p class="slds-text-body_regular">
            We couldn't reach the server. Check your connection and try again.
        </p>
        <div class="slds-m-top_medium">
            <lightning-button
                label="Retry"
                variant="brand"
                onclick={handleRetry}
            ></lightning-button>
        </div>
    </avonni-illustration>
</template>
```

**Result:** A large no-connection illustration with a title, explanatory message, and a brand Retry button.

### Example 2: Empty search results

**Scenario:** Replace an empty results list with a friendly empty-state graphic.

```html
<!-- emptyResults.html -->
<template>
    <avonni-illustration
        title="No results found"
        variant="desert"
        size="small"
        alternative-text="No results"
    >
        <p class="slds-text-body_small">
            Try adjusting your filters or search terms.
        </p>
    </avonni-illustration>
</template>
```

**Result:** A compact desert illustration with a title and guidance message in place of an empty list.

***

## Specifications

### Attributes

| Name               | Description                                                                                                                                                                                                                                                                                                                                                                                    | Type   | Default       | Required |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------- | -------- |
| `alternative-text` | The alternative text used to describe the illustration.                                                                                                                                                                                                                                                                                                                                        | String | —             |          |
| `size`             | The illustration size. Valid options include 'small', 'large'.                                                                                                                                                                                                                                                                                                                                 | String | `"small"`     |          |
| `title`            | The illustration title.                                                                                                                                                                                                                                                                                                                                                                        | String | —             |          |
| `variant`          | The variant types of illustrations. Valid values include text-only, going-camping, gone\_fishing, maintenance, desert, open-road, no-access, no-connection, not-available-in-lightning page-not-available, walkthrough-not-available, fishing-deals, lake-mountain, no-events, no-events-2, no-task, no-task-2, setup, gone-fishing, no-access-2, no-content, no-preview, preview and research | String | `"text-only"` |          |

### Slots

| Slot      | Description                                          |
| --------- | ---------------------------------------------------- |
| `default` | Placeholder for your content below the illustration. |

### Styling Hooks

| CSS Variable                                   | Type   | Default          |
| ---------------------------------------------- | ------ | ---------------- |
| `--avonni-illustration-title-text-color`       | color  | `#181818`        |
| `--avonni-illustration-title-font-size`        | font   | `1.25rem`        |
| `--avonni-illustration-title-font-style`       | font   | `normal`         |
| `--avonni-illustration-title-font-family`      | font   | `SalesforceSans` |
| `--avonni-illustration-title-font-weight`      | font   | `400`            |
| `--avonni-illustration-title-line-height`      | sizing | `1.25rem`        |
| `--avonni-illustration-title-letter-spacing`   | sizing | —                |
| `--avonni-illustration-content-text-color`     | color  | `#181818`        |
| `--avonni-illustration-content-font-size`      | font   | `1.25rem`        |
| `--avonni-illustration-content-font-style`     | font   | `normal`         |
| `--avonni-illustration-content-font-family`    | font   | `SalesforceSans` |
| `--avonni-illustration-content-font-weight`    | font   | `400`            |
| `--avonni-illustration-content-line-height`    | sizing | `1.25rem`        |
| `--avonni-illustration-content-letter-spacing` | sizing | —                |

## Key Considerations

* **Accessibility:** Provide `alternative-text` so screen readers describe the illustration.
* **Variant art:** The `variant` selects the SVG; `text-only` renders just the title and slot content with no graphic.
* **Sizing:** Only `small` and `large` are supported; choose based on available space.
* **Slot content:** Use the default slot for messages, icons, and action buttons.
* **Best Practice:** Always provide `alternative-text` for accessibility, and choose a `variant` whose art matches the state you're communicating (e.g. `no-connection` for offline).

***

## Troubleshooting Common Issues

* **No artwork appears:** Confirm `variant` is a supported value; `text-only` intentionally renders no graphic.
* **Illustration too large/small:** Set `size` to `small` or `large` to fit the container.
* **Message not showing:** Ensure your message and buttons are placed inside the component's default slot.
* **If issues persist:** Contact our support team at <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/illustration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.