Components

Banner

Banners identify official websites of government organizations in the United States. They also help visitors understand whether a website is official and secure.

Passed WCAG 2.1 AA

About the banner component

Note: Banners and identifiers are core components. We recommend using both core components on most sites. Together, they are the most recognizable and standardized design elements of a government site.

You should use the banner to identify your site as an official government site.

The banner explains how to identify an official .gov or .mil domain and that these sites have secure HTTPS connections. Using the banner component is the best way to assure visitors that they’re connected to an official site.

Most government sites should use the banner, but some should not use the banner. Do NOT use the banner on non-government domains such as a .com or .org.

If you are unable to update to USWDS 2.8.0 (described on GitHub) or higher but still want to include the new language in your banner, we recommend editing your content to the language outlined in the component preview.

When to use the banner component

  • To identify as an official government site. Most government sites should use the banner.

When to consider something else

  • If you don’t use a .gov/.mil domain and HTTPS. The Design System’s banner text identifies .gov and .mil domains and HTTPS as indicators that a website is an official government website. Use this banner only if your site uses both the proper top-level domain (TLD) and HTTPS.
  • Any time it would be misleading. The banner should be used to reduce confusion. Avoid using the banner on any site meant only for testing or otherwise not meant to be identified as an official government website.

Usability guidance

  • Use the provided text without customization. The banner is most effective as an identifier and a learning tool when its message is consistent across government sites. With only a few exceptions (described in our Implementation guidance), sites should use the TLD-appropriate text provided, unaltered. Use the Spanish version of the banner for Spanish-language websites.
  • Use the version appropriate to your website’s TLD. If your project uses a .mil top-level domain, use the .mil banner text.
  • Show the banner on every page. Use the banner at the top of every page of a site. It can be confusing or misleading if it appears on some pages and not others.
  • Avoid distraction. The banner should appear on every page of your site. Choose background colors that fit with your site theme, and avoid color combinations that draw excessive attention to the banner.
  • Keep the text up to date. Use the most current version of the banner.

Accessibility guidance

Test the banner component in your own project.

USWDS tested the banner component for accessibility. You should test your implementation, too.

Use banner accessibility tests
  • Use aria-label to give the banner a useful name. Our default markup uses aria-label="Official website of the United States government" or aria-label="Un sitio oficial del Gobierno de Estados Unidos" to distinguish the banner header from the main header.
  • The banner’s accordion uses JavaScript to set the aria-hidden value of its content area. To ensure your content remains accessible in the event the JavaScript does not load or is disabled, you should not set aria-hidden="true" on usa-banner__content.

Using the banner component

  • Some .mil websites do not belong to an official U.S. Department of Defense organization. These sites should adapt the Official websites use .mil section to use more technically accurate language: “A .mil website operates under the approval of the U.S. Department of Defense.”
  • The banner should directly follow the skipnav component.
  • Set the banner background color with $theme-banner-background-color. Banner text will update automatically.

Note: We recommend loading uswds-init.js when using banner, header, or modal components to assist in preventing flashes of unstyled content (FOUC) as well as cumulative layout shift (CLS). This small JavaScript file (less than 1 KB minified) helps the browser know if the USWDS JavaScript library is loading properly.

To add uswds-init to your site, simply copy uswds-init.js into your site assets from either the uswds-core/src/js package or the dist/js directory in the downloadable package. Then, reference the file in the <head> of your HTML files. Alternatively, you can inline its contents directly into a <script> tag in your HTML files.

Banner settings

Variable Description
$theme-banner-background-color

Background color of the banner and its content.
$theme-banner-font-family

The font family of the banner.
$theme-banner-link-color

The color of banner link. Add the link color and the system will generate the hover state. Default uses the default link settings calculated from your background color.
$theme-banner-max-width

Maximum width of the banner content.

Banner variants

This component has no variants.

Accessibility test status

The USWDS team did 14 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
14 12 0 2 0

Overview of recent accessibility test results:

  • Passed: 12
  • Passed with exceptions: 0
  • Conditional: 2
  • Failed: 0

Learn more on the banner accessibility tests page.

  • Package usage: @forward "usa-banner";
  • Dependencies: uswds-fonts, usa-media-block

Latest updates

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

Date USWDS version Affects Breaking Description
2024-06-07 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2687

2023-11-30 N/A
  • Markup
 Breaking

Breaking Fixed a bug causing component code example ID’s and relevant aria attributes to display incorrectly. Now, example ID’s match what’s found in the USWDS repo and are more succinct. More information: uswds-site#2312

2023-11-20 N/A
  • Guidance
 No

Updated the text in the aria-label documentation to match the component markup. More information: uswds-site#2149

2023-11-20 N/A
  • Guidance
 No

Removed usa-layout-grid from the list of dependencies. More information: uswds-site#2149

2023-11-09 3.7.0
  • JavaScript
 No

Updated the banner component so that it initializes without requiring import of the usa-accordion package. More information: uswds#5551

2023-11-09 3.7.0
  • Assets
 No

Optimized the us_flag_small.png icon and added a vector us_flag.svgicon. More information: uswds#5542

2023-09-29 3.6.1
  • Assets
 No

Improved horizontal alignment in icon-dot-gov.svg. More information: uswds#5370

2023-03-09 3.4.0
  • Styles
 No

Improved display of focus outline on mobile. Now the focus outline is visible all around the banner on mobile devices. More information: uswds#5013

2023-03-09 3.4.0
  • Styles
 No

Updated padding settings to accept any valid spacing token. More information: uswds#5076

2023-03-09 3.4.0
  • Styles
 No

Removed grid dependency from Banner. Banner no longer needs the usa-layout-grid package resulting in a much smaller package size. More information: uswds#5000

2022-10-09 3.2.0
  • Accessibility
  • Markup
 No

Updated the aria-label in English versions of banner. When read out on a screen reader, the statement “An official website of the United States government” can sound like “Unofficial website of the United States government”. To minimize confusion, we updated the component’s aria-label to instead read “Official website of the United States government”. More information: uswds#4925

2022-10-09 3.2.0
  • Accessibility
  • Markup
 No

Added aria-hidden attribute to the flag icon. The flag icon in the banner component is purely decorative and we can safely remove it from the screen reader readout. More information: uswds#4925

2022-10-09 3.2.0
  • Accessibility
  • Markup
 No

Simplified ARIA label in the lock SVG. We simplified the way we’re using aria-labelledby in the lock SVG to streamline screen reader vocalization. More information: uswds#4925

2022-08-05 3.1.0
  • JavaScript
  • Markup
 Breaking

Breaking Added type="button" to all non-form buttons to prevent default submit behaviors. This allowed us to remove preventDefault() from the relevant component JavaScript. More information: uswds#4695

2022-06-17 3.0.2
  • Assets
  • JavaScript
 No

Updated uswds-init.js to better suppress flashing content. We updated the uswds-init script’s event listener to target window from document. This assures that the page’s JavaScript is fully loaded before we remove the loadingClass that suppresses the open banner. The banner should no longer flash open. More information: uswds#4676

2022-06-17 3.0.2
  • Assets
 No

Updated flag icon to be high resolution. More information: uswds#4792

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-04-11 2.13.3
  • Accessibility
  • Styles
 No

Added support for forced colors mode. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610

2021-03-02 N/A
  • Guidance
 No

Updated guidance to identify banner as a core component. More information: uswds-site#1136

2020-12-17 2.10.0
  • Assets
  • JavaScript
 No

Introduced uswds-init.js to prevent banner flash. When added to the head of your document, this script prevents the banner from flashing its content on page load and shifting content. More information: uswds#3867

2020-12-17 2.10.0
  • Accessibility
  • Assets
 No

Improved the accessibility of decorative images in the banner. We modified the banner to properly mark up SVG files used as decorative images. Now all decorative images are hidden from screen readers, and all SVGs are more resilient to browser bugs. See the banner page for the complete, correct markup, and see the pull request for more context on the changes. More information: uswds#3892

2020-07-09 2.8.0
  • Content
 No

Updated banner copy. Updated the expanded text in the banner to emphasize that trustworthiness is a combination of an official TLD and a secure HTTPS connection. More information: uswds#3524

2020-07-09 2.8.0
  • Content
 No

Added Spanish versions. Included approved Spanish versions of the banner text. More information: uswds#3524

2020-07-09 2.8.0
  • Styles
 Breaking

Breaking Updated banner settings. Allowed users to change background color, link color, and link reverse colors. This update requires the use of Autoprefixer. More information: uswds#3531

2020-06-17 2.7.1
  • Accessibility
  • Assets
 No

Added role="img" to SVGs. More information: uswds#3316

2020-05-11 2.7.0
  • Styles
 No

Improved display of the “Here’s how you know” link in the gov banner. Now there’s no distracting change to the length of the underline on hover. More information: uswds#3427