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.

Critical alerts

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.

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.

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>

Title and description

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>,
    <Hds::Link::Inline @color="secondary" @href="#">inline</Hds::Link::Inline>
    <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.

General recommendations

• 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.

Actions

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

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

For content guidelines on actions, refer to Button and Link documentation.

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 you need to confirm that the user intended to interact with the action, consider displaying a confirmation modal.

Links

Within page and inline Alerts

When linking to internal and external resources in the Alert, default to using a secondary Standalone Link in the actions area. In the Ember component, these elements are passed as contextual components.

Within the Alert description, use the secondary Inline Link as the default link color. A common use case for this is when linking to multiple resources.

Wrap links to multiple related items on the same page in a list, e.g., when highlighting multiple form validation errors.

Within compact Alerts

As compact Alerts don’t support a title or actions, use secondary Inline Links in the description of the component. This matches the intended hierarchy of the component relative to other Alert types and supports linking to multiple resources.

If there is only one link within the compact alert, it’s acceptable to use the primary color, but this will result in increased prominence and elevated hierarchy.

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

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.