Components

Site alert

A site alert communicates urgent sitewide information.

About the site alert component

When your agency has urgent information to share with the public, it’s essential that it stands out from other content on the site. A site alert prominently displays critical, time-sensitive warnings or directions across every page so that users see it whenever they visit the site. Using the same site alert treatment across agencies helps create a consistent and predictable way for users to find urgent information across all government websites.

Standard informational site alert

Short alert message

Additional context and followup information including a link.

Standard emergency site alert

Emergency alert message

Additional context and followup information including a link.

Site alert with no header

Short alert message. Additional context and followup information including a link.

Site alert with list

Emergency alert message

• The primary emergency message and a link for supporting context.
• Another message, and another link.
• A final emergency message.

Slim site alert

Short alert message. Additional context and followup information including a link.

Site alert with no icon

Short alert message. Additional context and followup information including a link.

<h3 class="site-preview-heading">Standard informational site alert</h3>

<section class="usa-site-alert usa-site-alert--info" aria-label="Site alert,">
  <div class="usa-alert">
    <div class="usa-alert__body">
      <h3 class="usa-alert__heading">Short alert message</h3>
      <p class="usa-alert__text">
        Additional context and followup information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Standard emergency site alert</h3>

<section
  class="usa-site-alert usa-site-alert--emergency"
  aria-label="Site alert,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <h3 class="usa-alert__heading">Emergency alert message</h3>
      <p class="usa-alert__text">
        Additional context and followup information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Site alert with no header</h3>

<section
  class="usa-site-alert usa-site-alert--emergency usa-site-alert--no-heading"
  aria-label="Site alert,,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <p class="usa-alert__text">
        <strong>Short alert message.</strong> Additional context and followup
        information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Site alert with list </h3>

<section
  class="usa-site-alert usa-site-alert--emergency"
  aria-label="Site alert,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <h3 class="usa-alert__heading">Emergency alert message</h3>
      <ul class="usa-list">
        <li>
          The primary emergency message and
          <a class="usa-link" href="javascript:void(0);">a link</a> for
          supporting context.
        </li>
        <li>
          Another message,
          <a class="usa-link" href="javascript:void(0);">and another link</a>.
        </li>
        <li>A final emergency message.</li>
      </ul>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Slim site alert</h3>

<section
  class="usa-site-alert usa-site-alert--emergency usa-site-alert--slim"
  aria-label="Site alert,,,,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <p class="usa-alert__text">
        <strong>Short alert message.</strong> Additional context and followup
        information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Site alert with no icon</h3>

<section
  class="usa-site-alert usa-site-alert--emergency usa-site-alert--no-icon"
  aria-label="Site alert,,,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <p class="usa-alert__text">
        <strong>Short alert message.</strong> Additional context and followup
        information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Standard informational site alert</h3>

<section class="usa-site-alert usa-site-alert--info" aria-label="Site alert,">
  <div class="usa-alert">
    <div class="usa-alert__body">
      <h3 class="usa-alert__heading">Short alert message</h3>
      <p class="usa-alert__text">
        Additional context and followup information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Standard emergency site alert</h3>

<section
  class="usa-site-alert usa-site-alert--emergency"
  aria-label="Site alert,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <h3 class="usa-alert__heading">Emergency alert message</h3>
      <p class="usa-alert__text">
        Additional context and followup information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Site alert with no header</h3>

<section
  class="usa-site-alert usa-site-alert--emergency usa-site-alert--no-heading"
  aria-label="Site alert,,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <p class="usa-alert__text">
        <strong>Short alert message.</strong> Additional context and followup
        information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Site alert with list </h3>

<section
  class="usa-site-alert usa-site-alert--emergency"
  aria-label="Site alert,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <h3 class="usa-alert__heading">Emergency alert message</h3>
      <ul class="usa-list">
        <li>
          The primary emergency message and
          <a class="usa-link" href="javascript:void(0);">a link</a> for
          supporting context.
        </li>
        <li>
          Another message,
          <a class="usa-link" href="javascript:void(0);">and another link</a>.
        </li>
        <li>A final emergency message.</li>
      </ul>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Slim site alert</h3>

<section
  class="usa-site-alert usa-site-alert--emergency usa-site-alert--slim"
  aria-label="Site alert,,,,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <p class="usa-alert__text">
        <strong>Short alert message.</strong> Additional context and followup
        information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

<h3 class="site-preview-heading">Site alert with no icon</h3>

<section
  class="usa-site-alert usa-site-alert--emergency usa-site-alert--no-icon"
  aria-label="Site alert,,,,,"
>
  <div class="usa-alert">
    <div class="usa-alert__body">
      <p class="usa-alert__text">
        <strong>Short alert message.</strong> Additional context and followup
        information including
        <a class="usa-link" href="javascript:void(0);">a link</a>.
      </p>
    </div>
  </div>
</section>

Guidance

When to use the site alert component

• Critical system notifications. Use a site alert to deliver a static system status update, such as notices about unavailable services or content. Site alerts should appear by default and not in response to an action.
• Messages that should be displayed on every page. A site alert makes critical information obvious and findable on every page.

When to consider something else

• Responding to user actions. Use the alert component for page-level validation messages (like error messages on a form) or to inform a user that a task was completed successfully.
• Validating form input. On most forms, especially longer forms, validation messages should appear inline with error messages at the top of the form.

Usability guidance

• Place prominently. Use a full-width site alert positioned near the top of the page so it’s one of the first things users see.
• Avoid stacking multiple site alerts. If you need to convey more than one message, provide a list of links within a single site alert instead of multiple, stacked alerts.
• Avoid overwhelming use of color. It may be tempting to make heavy use of bright red or orange to draw attention to an emergency-related site alert. However, these colors can produce strong negative emotional reactions such as fear or panic. Positioning the banner at the top of the screen provides enough weight that such strong colors may not be necessary.

Accessibility

• Don’t visually hide alert messages and then make them visible when they are needed. Users of older assistive technologies may still be able to perceive hidden alert messages. Fully remove alert messages when they’re not needed.
• Include a descriptive ARIA label. Add an aria-label or aria-labelledby attribute to the .usa-site-alert element to ensure that your site alert appears in the landmarks menu. A well-written label can help assistive technology users easily find and understand the top-level information of your site alert.
• Add an ARIA role to dynamically-updated site alerts. For important, time-sensitive site alerts that will receive new content mid-session, for example if your site pushes out an updated emergency alert, add an ARIA role attribute that will notify users of changes. To do this, choose the appropriate role from the ARIA roles table and add it to the .usa-site-alert element.

Site alert ARIA roles

Attribute	Use Case
role="alert"	Important messages that demand the user's immediate attention. Use this role sparingly because it interrupts the user's workflow.
role="status"	Messages that provide advisory information but do not have the same urgency as alerts.

Reference: WAI-ARIA

Using the site alert component

Site alert settings

Variable	Description
$theme-site-alert-max-width	Maximum width of the site alert content.

Site alert variants

Variant	Description
usa-site-alert--info	Displays an information site alert.
usa-site-alert--emergency	Displays an emergency site alert.
usa-site-alert--slim	Display a slimmer version of the site alert.
usa-site-alert--no-icon	Display an site alert without an icon.

Package

• Package usage: @forward "usa-site-alert";
• Dependencies: usa-alert

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date	USWDS version	Affects	Breaking	Description
2023-03-09	3.4.0	Styles	No	Updated padding settings to accept any valid spacing token. More information: uswds#5076
2022-09-26	N/A	Guidance	No	Added guidance for using ARIA roles and ARIA labels. More information: uswds-site#1774
2022-10-19	3.2.0	Styles	No	Updated the alignment of site alert content to visually match banner content. The alert component was also updated. More information: uswds#4922
2022-04-28	3.0.0	Assets JavaScript Styles	Breaking	Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
2021-03-17	2.11.1	Assets	No	Restored missing white icons. Restored error--white, info--white, and warning--white icons. More information: uswds#4106
2021-03-17	N/A	Guidance	No	Updated and improved guidance for site alert. More information: uswds-site#1180
2021-03-17	2.11.0	Assets Styles	No	Provided better support for color icons that adapt to theme settings. Now the color of the alert icon will update automatically to adapt to the alert background, or to the color of the alert text. More information: uswds#4079
2021-03-17	2.11.0	Styles	No	Added the $theme-alert-padding-y setting. More information: uswds#4079