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.

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

  • Use aria-label to give the banner a useful name. Our default markup uses aria-label="official government website" 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.

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.

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

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

Date USWDS version Affects Breaking Description
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 high contrast mode and forced colors. 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
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
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