Alert

An alert appears when I need help or when something has changed. It may be time-sensitive.

The Alert component distinguishes important information or errors that wouldn't normally appear in a layout or template. They may blend into or disrupt a user's workflow. Disruptive notices are most effective if used sparingly and appear after user interaction.

Details

Extends: USWDS Alert component
Honeycrisp: Notice atom
Customization: Design tokens and Styles
Modifier: .cfa-alert

The Alert extends the USWDS Alert component. The visual appearance is modified using design tokens applied to the USWDS Alert component settings from the Honeycrisp Notice atom. Further customization is applied using the CSS modifier(s) .cfa-alert to add styles defined in a custom stylesheet.

Design tokens. Tokens define the name of basic system elements such as color, typography, or spacing. The values of tokens are relative to how the system defines them. This enables teams to alter the visual appearance of components yet remain within the system boundaries. Learn more about tokens on the Bixal's Design Tokens Guide.

Modifier. A modifier is a class name that applies a variant, type, or extended style customization to modify the component's visual appearance.

Examples

Informational, gray. For non-urgent messages or context that is important to find but should not interrupt a user’s workflow. The HTML element may have the role="region" attribute. If so, it must also have an aria-labelledby attribute that refers to the heading id. If it does not have a visible heading it must have an aria-label with the value of the label based on information inside the alert.

Can we ask about your race and identity?

Providing your race and ethnicity is optional and will not affect your individual application.

We will use this information to evaluate the fairness of this application, and we ask you to provide it to ensure that you are accurately represented. Learn more about how we protect your personal information.

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<div class="usa-alert cfa-alert usa-alert--info" role="region" aria-labelledby="aria-lb-9f4111fe79468">
  <div class="usa-alert__body">
    <div>
      <h3 class="usa-alert__heading" id="aria-lb-0ddb039c8baaa">Can we ask about your race and identity?</h3>
      <p>Providing your race and ethnicity is optional and will not affect your individual application.</p>
      <p>We will use this information to evaluate the fairness of this application, and we ask you to provide it to ensure that you are accurately represented. <a href="#">Learn more about how we protect your personal information</a>.</p>
    </div>
  </div>
</div>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "modifier": "cfa-alert usa-alert--info",
  "role": "region",
  "labelledby": "aria-lb-9f4111fe79468",
  "body": "<h3 class=\"usa-alert__heading\" id=\"aria-lb-0ddb039c8baaa\">Can we ask about your race and identity?</h3><p>Providing your race and ethnicity is optional and will not affect your individual application.</p><p>We will use this information to evaluate the fairness of this application, and we ask you to provide it to ensure that you are accurately represented. <a href=\"#\">Learn more about how we protect your personal information</a>.</p>"
}

Success, green. For successful interactions such as a submitting an application. The HTML element should have the role="status" attribute.

Done! Your application has been submitted.

You were recommended for expedited food assistance (SNAP). Click here to learn more about expedited food assistance.

View HTML

<div class="usa-alert cfa-alert usa-alert--success" role="status">
  <div class="usa-alert__body">
    <div>
      <h3 class="usa-alert__heading">Done! Your application has been submitted.</h3>
      <p class="usa-alert__text">You were recommended for expedited food assistance (SNAP). <a href="#">Click here to learn more about expedited food assistance</a>.</p>
    </div>
  </div>
</div>

View context passed to this component

{
  "modifier": "cfa-alert usa-alert--success",
  "role": "status",
  "body": "<h3 class=\"usa-alert__heading\">Done! Your application has been submitted.</h3><p class=\"usa-alert__text\">You were recommended for expedited food assistance (SNAP). <a href=\"#\">Click here to learn more about expedited food assistance</a>.</p>"
}

Warning, yellow. For urgent messages or context that is important to find but should not interrupt a user’s workflow. The HTML element may have the role="region" attribute. If so, it must also have an aria-labelledby attribute that refers to the heading id. If it does not have a visible heading it must have an aria-label with the value of the label based on information inside the alert.

Make sure your address is correct

We couldn't find your address. To make sure you get mail from the county, you may edit your address or keep going. Alternatively, click here to look up your county information.

View HTML

<div class="usa-alert cfa-alert usa-alert--warning">
  <div class="usa-alert__body">
    <h3 class="usa-alert__heading">Make sure your address is correct</h3>
    <div>
      <p class="usa-alert__text">We couldn't find your address. To make sure you get mail from the county, you may edit your address or keep going. <a href="#">Alternatively, click here to look up your county information</a>.</p>
    </div>
  </div>
</div>

View context passed to this component

{
  "modifier": "cfa-alert usa-alert--warning",
  "heading": "Make sure your address is correct",
  "body": "<p class=\"usa-alert__text\">We couldn't find your address. To make sure you get mail from the county, you may edit your address or keep going. <a href=\"#\">Alternatively, click here to look up your county information</a>.</p>"
}

Error, red. For urgent messages or application failure messages that are out of the user’s control. Error messages should rarely appear. The HTML element should have role="alert" attribute.

Error notice

This is an example error notice. Its a great way to highlight errors or dangerous issues. Here is a link to more information.

View HTML

<div class="usa-alert cfa-alert usa-alert--error" role="alert">
  <div class="usa-alert__body">
    <div>
      <h3 class="usa-alert__heading">Error notice</h3>
      <p class="usa-alert__text">This is an example error notice. Its a great way to highlight <strong>errors or dangerous issues</strong>. <a href="#">Here is a link to more information</a>.</p>
    </div>
  </div>
</div>

View context passed to this component

{
  "modifier": "cfa-alert usa-alert--error",
  "role": "alert",
  "body": "<h3 class=\"usa-alert__heading\">Error notice</h3><p class=\"usa-alert__text\">This is an example error notice. Its a great way to highlight <strong>errors or dangerous issues</strong>. <a href=\"#\">Here is a link to more information</a>.</p>"
}

Emergency, orange warm. For time sensitive messages that provide urgent advisory information. Emergency messages must be used sparingly. The HTML element should have role="status" attribute. For time-sensitive messages that demand the user's immediate attention and interrupt their workflow the HTML element should have role="alert" attribute.

Emergency alert message

Additional context and followup information including a link.

View HTML

<div class="usa-alert cfa-alert usa-alert--emergency" role="status">
  <div class="usa-alert__body">
    <div>
      <h3 class="usa-alert__heading">Emergency alert message</h3>
      <p class="usa-alert__text">Additional context and followup information including <a href="#">a link</a>.</p>
    </div>
  </div>
</div>

View context passed to this component

{
  "modifier": "cfa-alert usa-alert--emergency",
  "role": "status",
  "body": "<h3 class=\"usa-alert__heading\">Emergency alert message</h3><p class=\"usa-alert__text\">Additional context and followup information including <a href=\"#\">a link</a>.</p>"
}

Guidance

Writing messages. Use Plain language, be empathetic, and use trauma-informed principles when writing message content.

Heading order. It is a best practice to ensure the alert heading level does not skip and is in order with other page headings. However, this does not contribute to accessible success criteria.

Attention and color. A notice that uses a tertiary background color, or color that appears in roughly 5% of the color palette, will draw more attention. Also consider choosing combinations that are distinguishable across a broad spectrum of color blindness such as blue against orange, where orange is the emphasis color.

Refer to additional guidance on the USWDS documentation site.

USWDS documentation site

Additional references

Accessibility

Customization to the visual appearance of the Alert has been verified for WCAG 2.1 AA contrast minimum success.
The Alert examples pass manual audits (WCAG 2.1 AA using axe or Lighthouse).
The Alert achieves WCAG 2.1 AA resizing success.
Resizing text up to 200% without loss of content or functionality.
The Alert passes keyboard interaction tests.
No keyboard test has been created.
The Alert passes screen reader interaction tests.
Guidance on ensuring Alert accessibility has been provided in this documentation.

Refer to additional accessibility guidance on the USWDS documentation site.

Checklist Key

Passes
Unchecked

Design library component

Source and usage

Package: @codeforamerica/uswds/packages/cfa-alert

Sass stylesheet: ./_cfa-alert.scss
Thymeleaf template fragment: ./cfa-alert.th.html
Embedded Ruby (ERB) partial template: ./_cfa-alert.html.erb

Packages are collections of functionality that make up a component. Typically, they include stylesheets, templates, and scripts. Learn more about packages on the USWDS documentation site.

Sass theme settings

Below is a demonstration of customizing the component theme settings. Refer to the theme and package-level settings documentation.

// Theme-level settings
@use 'cfa-uswds-theme' with (
  // Global theme settings that affect the component, changing these will affect other components
  $cfa-color-info-lighter: 'gray-warm-4',       // Affects the background color of informational alerts
  $cfa-color-info-light: 'gray-warm-20',        // Affects border color of informational alerts
  $cfa-color-warning-lighter: 'gold-5v',        // Affects the background color of warning alerts
  $cfa-color-warning: 'gold-20v',               // Affects border color of informational alerts
  $cfa-color-error-lighter: 'orange-warm-10v'   // Affects the background color of error alerts
  $cfa-color-error: 'orange-warm-50v',          // Affects border color of error alerts
  $cfa-color-success-lighter: 'green-cool-5v',  // Affects the background color of success alerts
  $cfa-color-success-darker: 'green-cool-60v',  // Affects border color of success alerts
  $cfa-color-emergency: 'orange-warm-30v'       // Affects the background color of emergency alerts
  $cfa-color-emergency-dark: 'orange-warm-60v', // Affects border color of emergency alerts
  // Component specific settings
  $cfa-alert-bar-width: 0,
  $cfa-alert-padding-x: 2,
  $cfa-alert-padding-y: 2,
  $cfa-alert-link-color: 'ink'
);
// Package-level settings
@use 'cfa-core' with (
  $cfa-alert-border-width: 2px
);

// Theme-level settings
@use 'cfa-uswds-theme' with (
  // Global theme settings that affect the component, changing these will affect other components
  $cfa-color-info-lighter: 'gray-warm-4',       // Affects the background color of informational alerts
  $cfa-color-info-light: 'gray-warm-20',        // Affects border color of informational alerts
  $cfa-color-warning-lighter: 'gold-5v',        // Affects the background color of warning alerts
  $cfa-color-warning: 'gold-20v',               // Affects border color of informational alerts
  $cfa-color-error-lighter: 'orange-warm-10v'   // Affects the background color of error alerts
  $cfa-color-error: 'orange-warm-50v',          // Affects border color of error alerts
  $cfa-color-success-lighter: 'green-cool-5v',  // Affects the background color of success alerts
  $cfa-color-success-darker: 'green-cool-60v',  // Affects border color of success alerts
  $cfa-color-emergency: 'orange-warm-30v'       // Affects the background color of emergency alerts
  $cfa-color-emergency-dark: 'orange-warm-60v', // Affects border color of emergency alerts
  // Component specific settings
  $cfa-alert-bar-width: 0,
  $cfa-alert-padding-x: 2,
  $cfa-alert-padding-y: 2,
  $cfa-alert-link-color: 'ink'
);
// Package-level settings
@use 'cfa-core' with (
  $cfa-alert-border-width: 2px
);

USWDS theme settings

Refer to the usage documentation for additional USWDS theme settings.

@use "uswds-core" with ( /* additional USWDS theme settings */ );

Thymeleaf template fragment

This is the pre-rendered template fragment from the package. It is the same template used to render the demonstrations above. You may copy and paste from this example or use the template using the th:block th:replace tag. See the example below.

<div th:fragment="alert(modifier, role, label, labelledby, heading, body, text)" class="usa-alert" th:classappend="${modifier}" th:attr="role=${role},aria-label=${label},aria-labelledby=${labelledby}">
  <div class="usa-alert__body">
    <h3 class="usa-alert__heading" th:if="${heading}" th:text="${heading}" th:attr="id=${labelledby}">Heading</h3>
    <div th:if="${body}" th:utext="${body}">
      <p>Body</p>
    </div>
    <p class="usa-alert__text" th:if="${text}" th:utext="${text}">Text</p>
  </div>
</div>

Template fragment inclusion

Below is an example of how to use the fragment from the package directory using the th:block th:replace inclusion tag. Replace the fragment parameters using your variables or context.

<th:block th:replace="~{packages/cfa-alert/cfa-alert.th :: alert(${modifier}, ${role}, ${label}, ${labelledby}, ${heading}, ${body}, ${text})}" />

ERB template partial

This is the pre-rendered partial template from the package. You may copy and paste from this example or use the template directly from the path.

<div class="usa-alert<% if defined?(modifier) %> <%= modifier %><% end %>"<% if defined?(role) %> role="<%= role %>"<% end %><% if defined?(label) %> aria-label="<%= label %>"<% end %><% if defined?(labelledby) %> aria-labelledby="<%= labelledby %>"<% end %>>
  <div class="usa-alert__body">
    <% if defined?(heading) %><h3 class="usa-alert__heading"<% if defined?(labelledby) %> id="<%= labelledby %>"<% end %>><%= heading %></h3><% end %>
    <% if defined?(body) %><div><%= body %></div><% end %>
    <% if defined?(text) %>
      <p class="usa-alert__text"><%= text %></p>
    <% end %>
  </div>
</div>

Partial render

Below is an example of how to include the partial in a view from the package directory using the Ruby ERB class. Replace the argument values using your variables or context. In a Rails environment, the render method can be used instead with the same hash values.

<%= ERB.new(File.read('packages/cfa-alert/_cfa-alert.html.erb'), 0, 0, '@alert').result_with_hash({modifier: modifier, role: role, label: label, labelledby: labelledby, heading: heading, body: body, text: text}) %>

Have a suggestion or need help?