Alert

Use alerts to display brief but important system-generated messages. They attract the user’s attention without interrupting their task. For messages that are the result of a user’s actions, see Toast.

Types of alerts

There are three types of alerts: page, inline, and compact.

Page

Use page-level alerts on the top of the page, between the navigation and the breadcrumb to inform users of an event that may require the user’s attention or action.

Inline

Use inline alerts when the message is contextual or specific to the section it’s placed in.

Compact

Use compact alerts when a less prominent alert is needed.

Usage

When to use

• To display a concise, important message that requires the user’s attention.

When not to use

• To communicate feedback on a user’s action, consider Toast.
• As a dialog to confirm an action, consider Modal.
• To flag new features (e.g., "In Preview", "Beta", "New", etc), consider Badge.

Color

Use color logically.

• Neutral to provide general information to the user regarding the current context or relevant actions.
• Highlight to provide general or promotional information to the user prominently.
• Success to indicate a successful action.
  • Use the success variant sparingly. To communicate success after a user action is performed, use Toast.
• Warning to help users avoid an issue. Provide guidance and actions, if possible.
• Critical to indicate critical errors that need immediate action.

Icons

All alerts have icons by default that are intentionally tied to the alert type.

Icons within the neutral and highlight alerts can be replaced with other icons. Change them only when the new icon provides the user with extra value; otherwise, use the default icon provided.

Dismissal

Persistent

All alerts are persistent by default, while compact alerts are always persistent.

Dismissible

Page and inline alerts can be dismissible.

We recommend setting neutral and highlight alerts to be dismissible, as they are not critical for users to complete their journey.

We recommend keeping critical alerts non-dismissible as they are essential to the user’s journey and can get dismissed by mistake.

Actions

Use small buttons to avoid competing with other actions on the page. Use more than two actions sparingly.

Buttons

We recommend using the secondary button variant for primary actions and the tertiary button variant for secondary actions.

Usage of critical buttons

Avoid using critical buttons in alerts. We handle the prominence and importance via the styling of the alert container itself. If needing to confirm that the user intended to interact with the action, consider displaying a confirmation modal.

Links

Use Standalone Link when an action takes the user to a new destination (URL).

We recommend using the secondary standalone link to maintain visual hierarchy and avoid competing prominence when used with the secondary button.

Placement

Page

Page alerts are placed between the global header navigation and the breadcrumb, next to the left navigation.

Inline

Inline alerts can be added to a section or component or inline with content.

Compact

Compact alerts can be added to a section or component or inline with content.

Composition

Page and inline alerts can be configured in a variety of ways. For example:

With icon and title

With icon, title, and description

Title and description only

The title or description should contain the alert type, e.g., “Warning,” if no icon is present.

With actions

With generic content

Content

• Keep the title short, as this will be the most prominent element when users scan the alert.
• Avoid ending the title with a period.
• Alert descriptions should be short but clear enough to explain what’s happening. We recommend keeping messages under 90 characters.
• For warning and critical alerts, guide the users on how to prevent or fix the issue.
• For content guidelines on actions, refer to Button and Link documentation.

Related

• Toast
• Modal

How to use this component

The most basic invocation requires the type argument to be passed, along with the title and/or description content. By default, a neutral Alert is generated.

<Hds::Alert @type="inline" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
</Hds::Alert>

Type

A different type of Alert can be invoked using the type argument.

<Hds::Alert @type="page" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
</Hds::Alert>

<Hds::Alert @type="compact" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
</Hds::Alert>

Content

Optionally, you can pass only title or only description.

<Hds::Alert @type="inline" as |A|>
  <A.Title>Title here</A.Title>
</Hds::Alert>

<Hds::Alert @type="inline" as |A|>
  <A.Description>Description here</A.Description>
</Hds::Alert>

Color

A different color can be applied to the Alert using the color argument. This will determine the default icon used in the Alert, unless overwritten.

<Hds::Alert @type="inline" @color="success" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
</Hds::Alert>

Icons

A different icon can be used in the Alert using the icon argument. This accepts any icon name.

<Hds::Alert @type="inline" @color="success" @icon="bulb" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
</Hds::Alert>

If you need to hide the icon, pass false to the icon argument. This is only an option on page and inline Alerts as compact Alerts require an icon.

<Hds::Alert @type="inline" @color="success" @icon={{false}} as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
</Hds::Alert>

Dismissal

To enable dismissibility, pass a callback function to the onDismiss argument. This will add a dismiss button to the Alert. When that button is clicked, the callback function will be executed.

Given the variety of use cases and contexts in which alerts are used across products, application teams will need to implement the callback function.

<Hds::Alert @type="inline" @color="warning" @onDismiss={{this.noop}} as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
</Hds::Alert>

Actions

Actions can be passed to the component using one of the suggested Button or Link::Standalone contextual components.

<Hds::Alert @type="inline" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
  <A.Button @text="Your action" @color="secondary" {{on "click" this.yourOnClickFunction}} />
  <A.Link::Standalone @color="secondary" @icon="arrow-right" @iconPosition="trailing" @text="Another action" @href="#" />
</Hds::Alert>

Structured content

When needed, the Description contextual component can contain logic, rich HTML, or structured content.

pre

<Hds::Alert @type="inline" @color="success" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>
    The description can contain
    {{#if true}}conditional logic{{/if}}, Ember components, and HTML tags, like
    <strong>strong text</strong>,
    <em>emphasized text</em>,
    <code>code</code>,
    <pre>pre</pre>,
    <a href="#">inline</a>
    <LinkTo @route="index">links</LinkTo>.
  </A.Description>
</Hds::Alert>

You can pass more than one D.Description contextual component to have multiple description lines.

<Hds::Alert @type="inline" @color="success" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>First line of description.</A.Description>
  <A.Description>Second line of description.</A.Description>
</Hds::Alert>

Generic content

Use the Generic contextual component to insert custom content. Generic content will appear after the title, description, and actions. Application teams will need to implement spacing, layout, and styling for generic content.

<Hds::Alert @type="inline" as |A|>
  <A.Title>Title here</A.Title>
  <A.Description>Description here</A.Description>
  <A.Generic>
    [your content here]
  </A.Generic>
</Hds::Alert>

Component API

Contextual components

Title, description, actions, and generic content are passed into the alert as yielded components, using the Title, Description, Button, Link::Standalone, Generic keys.

Anatomy

Page and inline alerts

Compact alerts

Conformance rating

Alerts are conformant when there are no interactive elements present inside of the alert. There is future work planned to make this component WCAG conformant by adding support for the correct ARIA roles when interactive elements are contained within the alert.

Best practices

Notification

An Alert is a live region with important, usually time-sensitive information. The use of this alert component will cause immediate notifications for users with assistive technology.

Dismissing the alert

Since alerts are not required to receive focus, it should not be required that the user close the alert.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.