> 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/alert-banner.md).
# Alert Banner
`avonni-alert-banner`
Alert banners communicate a state that affects the entire system, not just a feature or page. It persists over a session and appears without the user initiating the action.
## Overview
**Alert Banner** is a Lightning Web Component that displays a persistent, system-level message communicating a state that affects the whole application rather than a single feature.
Use it in your own Lightning Web Components to surface maintenance notices, errors, warnings, or offline status. You control the icon, the styling variant, whether the banner can be dismissed, and the message content via the default slot.
### Use Cases
* **Maintenance notices:** Warn users of an upcoming release or downtime window.
* **Error states:** Flag failed payments or processing errors that need action.
* **Capacity warnings:** Alert users when storage or quotas are almost full.
* **Offline status:** Indicate lost connectivity and pending sync with the `offline` variant.
* **Dismissible alerts:** Let users close non-blocking notifications once read.
***
## Variant Guidelines
| Variant | Use Case |
| --------- | --------------------------------------------- |
| `base` | Neutral, informational system messages. |
| `warning` | Cautionary states (e.g. storage almost full). |
| `error` | Blocking or failed states needing action. |
| `offline` | Connectivity or sync status. |
***
## Use Case Examples
### Example 1: Informational maintenance banner
**Scenario:** Notify users of a scheduled maintenance window at the top of a custom app page.
```html
A new release is scheduled for this weekend. Save your work before the
maintenance window begins.
```
**Result:** A neutral banner with an info icon spanning the top of the page.
### Example 2: Dismissible error banner
**Scenario:** Surface a failed payment that the user can acknowledge and close.
```html
We could not process your last payment. Update your billing details to
avoid service interruption.
```
```js
// billingAlert.js
import { LightningElement } from 'lwc';
export default class BillingAlert extends LightningElement {
handleClose() {
// Banner dismissed; record acknowledgement or hide related UI.
}
}
```
**Result:** A red error banner with a close button; clicking it fires `close` and removes the banner.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------- | -------- |
| `icon-name` | The Lightning Design System name of the icon. Specify the name in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to be displayed. | String | — | |
| `icon-size` | The size of the icon. Options include xx-small, x-small, small, medium, or large. | String | `"small"` | |
| `is-dismissible` | Specify if the alert can be closed. | Boolean | `false` | |
| `variant` | The variant change the apparence of the alert. Valid values include base, error, offline and warning. | String | `"base"` | |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| ------- | --------------------------------------------- | ------------- | ------------- | -------------------- |
| `focus` | Set the focus on the close button, if present | | | |
### Slots
| Slot | Description |
| --------- | ------------------------------------------ |
| `default` | Placeholder for your content in the alert. |
### Custom Events
#### `blur`
The event fired when the focus is removed from the close button.
The `blur` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `close`
The event fired when the alert is closed.
The `close` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | ---------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | true | This event can be canceled. You can call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `focus`
The event fired when the focus is set on the close button.
The `focus` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
### Styling Hooks
| CSS Variable | Type | Default |
| ------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--avonni-alert-base-color-background` | color | `#747474` |
| `--avonni-alert-base-text-color` | color | `#ffffff` |
| `--avonni-alert-base-icon-color-foreground` | color | — |
| `--avonni-alert-base-icon-color-foreground-default` | color | `#ffffff` |
| `--avonni-alert-base-close-icon-color-foreground-default` | color | `#ffffff` |
| `--avonni-alert-base-icon-color-background` | color | — |
| `--avonni-alert-warning-color-background` | color | `#dd7a01` |
| `--avonni-alert-warning-text-color` | color | `#080707` |
| `--avonni-alert-warning-icon-color-foreground` | color | — |
| `--avonni-alert-warning-icon-color-foreground-default` | color | `#514f4d` |
| `--avonni-alert-warning-icon-color-background` | color | — |
| `--avonni-alert-warning-close-icon-color-foreground-default` | color | `#514f4d` |
| `--avonni-alert-error-color-background` | color | `#ba0517` |
| `--avonni-alert-error-text-color` | color | `#ffffff` |
| `--avonni-alert-error-icon-color-foreground` | color | — |
| `--avonni-alert-error-icon-color-foreground-default` | color | `#ffffff` |
| `--avonni-alert-error-icon-color-background` | color | — |
| `--avonni-alert-error-close-icon-color-foreground-default` | color | `#ffffff` |
| `--avonni-alert-offline-color-background` | color | `#444` |
| `--avonni-alert-offline-text-color` | color | `#ffffff` |
| `--avonni-alert-offline-icon-color-foreground` | color | — |
| `--avonni-alert-offline-icon-color-foreground-default` | color | `#ffffff` |
| `--avonni-alert-offline-icon-color-background` | color | — |
| `--avonni-alert-offline-close-icon-color-foreground-default` | color | `#ffffff` |
| `--avonni-alert-spacing-block-start` | dimension | `0.5rem` |
| `--avonni-alert-spacing-inline-end` | dimension | `2rem` |
| `--avonni-alert-spacing-block-end` | dimension | `0.5rem` |
| `--avonni-alert-spacing-inline-start` | dimension | `0.5rem` |
| `--avonni-alert-content-horizontal-alignment` | alignment | `center` |
| `--avonni-alert-font-weight` | font | `400` |
| `--avonni-alert-font-size` | font | `1em` |
| `--avonni-alert-font-style` | font | `normal` |
| `--avonni-alert-image-background` | image | `linear-gradient(45deg, rgba(24, 24, 24, 0.1) 25%, transparent 25%, transparent 50%, rgba(24, 24, 24, 0.1) 50%, rgba(24, 24, 24, 0.1) 75%, transparent 75%, transparent))` |
| `--avonni-alert-icon-radius-border` | dimension | `0.25rem` |
| `--avonni-alert-color-border` | color | `transparent` |
| `--avonni-alert-sizing-border` | sizing | `1px` |
| `--avonni-alert-styling-border` | styling | `solid` |
| `--avonni-alert-radius-border` | dimension | `0` |
| `--avonni-alert-size-background` | dimension | `64px 64px` |
## Key Considerations
* **Persistence:** Alert banners are meant to communicate system-wide state, not transient feedback—use a toast for short-lived notifications.
* **Dismissibility:** Only set `is-dismissible` for non-blocking messages; keep critical errors visible until resolved.
* **Icon meaning:** Pair `icon-name` with the variant so the icon reinforces the message severity.
* **Content slot:** Place the message text directly inside the tag; it renders in the default slot.
* **Best Practice:** Match the variant to the severity of the message (e.g. `error` for blocking issues, `offline` for connectivity), and choose an `icon-name` that reinforces that meaning.
***
## Troubleshooting Common Issues
* **Banner not visible:** Confirm message content is provided inside the tag and the component is rendered in your template.
* **No close button:** The close button only appears when `is-dismissible` is set; add the attribute to enable dismissal.
* **Wrong color:** Verify the `variant` value matches an accepted option; an unknown value falls back to `base`.
* **If issues persist:** Contact our support team at 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/alert-banner.md?ask=&goal=
```
`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.