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