# Alert

> Alerts show a short, important message, without interrupting what someone is doing.

Source: https://contributors.home-assistant.io/design/components/alert/

Live demo of `ha-alert`.

```html
<ha-alert alert-type="error">Could not connect to the device.</ha-alert>
<ha-alert alert-type="warning">This update requires a restart.</ha-alert>
<ha-alert alert-type="info">You can change this later in the settings.</ha-alert>
<ha-alert alert-type="success">Backup created.</ha-alert>
```

## Overview

An alert draws attention to a message on the page itself. It does not block anything: people can read it and continue. Its type, shown by a color and an icon, tells how serious the message is.

## When to use

Use an alert for:

- An error that someone needs to know about, with what to do about it
- A warning about something that needs attention, or could go wrong
- Useful context, like a tip or a change to be aware of
- Confirming that something worked

Don't use an alert for:

- A decision someone must make before they can continue. Use a [dialog](https://contributors.home-assistant.io/design/components/dialog/).
- A short label or status next to something else. Use a [badge](https://contributors.home-assistant.io/design/components/badge/).
- Extra help that only shows on hover. Use a [tooltip](https://contributors.home-assistant.io/design/components/tooltip/).

## Anatomy

1. **Container**: the tinted background, in the color of the type
2. **Icon**: the icon of the type, or your own icon
3. **Title**: optional, in bold above the message
4. **Message**: the text of the alert
5. **Action**: optional, a dismiss button or your own action, like a button

## Variants

### Type

There are four types. Each has its own color and icon:

- **Error**: something went wrong. Say what, and what to do about it.
- **Warning**: something needs attention, or could go wrong.
- **Info**: useful context, like a tip or a change to be aware of. This is the default.
- **Success**: something worked as intended.

### With a title

A title adds a bold line above the message. Use it together with a message, never on its own.

Live demo of `ha-alert`.

```html
<ha-alert alert-type="warning" title="Restart required">This update requires a restart.</ha-alert>
```

### Dismissable or with an action

A dismissable alert gets a close button. You can also put your own action in the alert, like a button to undo.

Live demo of `ha-alert`, `ha-button`, connected to a demo Home Assistant.

```html
<ha-alert alert-type="info" dismissable>You can change this later in the settings.</ha-alert>
<ha-alert alert-type="success">Backup created.<ha-button slot="action" appearance="plain">Undo</ha-button></ha-alert>
```

### Narrow

In the narrow version, the action moves below the message instead of next to it. This helps in small spaces, like a card.

## Behavior

- An alert has no hover, focus, or pressed state of its own. Only the action inside it, like the dismiss button, has those.
- Selecting the dismiss button does not remove the alert. It sends an event, and the page that shows the alert decides what happens, usually hiding it.
- Long text wraps, and long words break, so the message always fits.
- When there is no title, the icon is centered next to the message. With a title, it lines up with the title.
- The alert is laid out left to right, unless its title starts with Hebrew or Arabic text. Then it follows the direction of the page.

## Specs

| Property | Value | Token |
| --- | --- | --- |
| Padding | 8px | `--ha-alert-padding` |
| Icon size | 24px | `--ha-alert-icon-size` |
| Space between icon and message | 8px | None |
| Corner radius | 4px | `--ha-border-radius-sm` |
| Background | The type color at 12% opacity | See below |
| Title weight | 700 | `--ha-font-weight-bold` |
| Dismiss button size | 36px | `--ha-icon-button-size` |

| Type | Icon | Icon and background color |
| --- | --- | --- |
| Error | Alert circle outline | `--error-color`, `#db4437` |
| Warning | Alert outline | `--warning-color`, `#ffa600` |
| Info | Information outline | `--info-color`, `#039be5` |
| Success | Checkbox marked circle outline | `--success-color`, `#43a047` |

The message text has no color of its own: it uses the text color of the page around it.

## Guidelines

Do and don't, as live demos.

**Do:** Say what went wrong, and what to do about it.

```html
<ha-alert alert-type="error">Could not connect to the device. Check that it is turned on and connected to your network.</ha-alert>
```

**Don't:** Only say that something went wrong.

```html
<ha-alert alert-type="error">An error occurred.</ha-alert>
```

Do and don't, as live demos.

**Do:** Use a title together with a message.

```html
<ha-alert alert-type="warning" title="Restart required">This update requires a restart.</ha-alert>
```

**Don't:** Use a title without a message.

```html
<ha-alert alert-type="warning" title="Restart required"></ha-alert>
```

## Accessibility

### Keyboard

The alert itself does not take focus. Its action does:

| Key | Action |
| --- | --- |
| <kbd>Tab</kbd> | Moves focus to the dismiss button or your own action. |
| <kbd>Enter</kbd> or <kbd>Space</kbd> | Selects the focused button. |

### Target size

The dismiss button is 36px by 36px.

### Screen readers

- When an alert appears on a page that is already open, most screen readers read it out right away. An alert that is already there when the page loads is not announced.
- Color and icon don't reach someone who uses a screen reader, so the text must make the type clear on its own.
- The dismiss button is announced as "Dismiss alert", in the language of the user.

### In the code

- The alert has the role `alert`.
- The icon is an `ha-svg-icon`, which is hidden from screen readers with `aria-hidden="true"`.
- The dismiss button is an icon button with the translated label `ui.common.dismiss_alert` as its accessible name.

## Related

- [Dialog](https://contributors.home-assistant.io/design/components/dialog/): when someone must respond before continuing
- [Badge](https://contributors.home-assistant.io/design/components/badge/): a short status next to something
- [Color](https://contributors.home-assistant.io/design/foundations/color/): the colors behind the types
- [UI text](https://contributors.home-assistant.io/design/ui-text/): how to write the message

## In code

The element is `<ha-alert>`, with the type set through `alert-type`:

```html
<ha-alert alert-type="error">Could not connect to the device.</ha-alert>
<ha-alert alert-type="warning" title="Restart required">
  This update requires a restart.
</ha-alert>
<ha-alert alert-type="success" dismissable>Backup created.</ha-alert>
```

### Attributes

- `alert-type`: `info` (default), `warning`, `error`, or `success`.
- `title`: a title, shown in bold above the message.
- `dismissable`: shows a dismiss button.
- `narrow`: puts the action below the message.

### Slots

- Default: the message.
- `icon`: replaces the icon of the type.
- `action`: your own action, like a button. It replaces the dismiss button.

### Events

- `alert-dismissed-clicked`: fired when the dismiss button is selected. Remove or hide the alert in response.

### Styling

- `--ha-alert-padding`: the padding. Defaults to 8px.
- `--ha-alert-icon-size`: the size of the icon. Defaults to 24px.

Source: [`src/components/ha-alert.ts`](https://github.com/home-assistant/frontend/blob/dev/src/components/ha-alert.ts)