Components

Banner

The banner identifies official websites of government organizations in the United States. It also helps visitors understand how to tell that a website is both official and secure.

About the banner component

Note: Banner is a core component along with the identifier component. 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 that the combination of (a) an official .gov or .mil domain and (b) a secure HTTPS connection are 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 or higher but you still want to include the new language in your banner, we recommend editing your content to the language outlined below.

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 banner text identifies .gov/.mil domains and HTTPS as indicators that a website is an official government website. Use the banner only if your site uses both the proper 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 websites. With only a few exceptions (see 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 appears 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 that your content is accessible in the event that 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 authority 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: @import usa-banner
  • Requires: required, global