Skip to main content

An official website of the United States government

Here's how you know

An official website of the United States government

Here's how you know

Theme:

Design system switcher

Version:

Design system switcher

Theme:

Design system switcher

Version:

Design system switcher

USA Banner

The USA 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.

Example

Localization options

English and Spanish translations of <USABanner /> are available through Storybook.

To change the language in which a component is rendered, use the dropdown menu called šŸŒ Language in Storybook's toolbar and select your language. Examples with available English and Spanish translations will automatically change to reflect the selected language.

Code

React

Review Storybook for React guidance of this component.

Web Component

Go to Storybook for Web Component guidance of this component.

Style customization

The following CSS variables can be overridden to customize UsaBanner components:

CSS variables for usa-banner
VariableDefault Core Theme Value
--usa-banner__background-colorhex value: #f2f2f2--color-gray-lightest
--usa-banner-domain-icon__colorhex value: #0071bc--color-primary
--usa-banner-close-button__color--mobilehex value: #0071bc--color-primary
--usa-banner-close-button__background-color--mobilehex value: #d9d9d9--color-gray-lighter
--usa-banner-security-icon__colorhex value: #59ac56--color-success-light
Notice:

The USA Banner uses predefined variables from a theme's global tokens to determine the default width of its content and gutters (padding).

For most applications this should be sufficient, but for others with custom layouts it can result in the banner's content appearing misaligned with the content of the rest of a page. To fix this, you can customize the --usa-banner__max-width and --usa-banner-gutter-width variables to match the application's page width and gutter width.

To illustrate how this works, here's an example of how to customize the banner's width and gutter width for an application with more narrow content:

/* These values can be whatever you need them to be */
:root {
  --usa-banner__max-width: 600px;
  --usa-banner-gutter-width: 1rem;
}

Guidance

When to use

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

When to consider alternatives

  • If you don't use a .gov domain and HTTPS. The banner text identifies .gov 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.

Usage

  • 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.
  • 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 testing

Keyboard testing

  • Confirm that the banner can be accessed, opened, and closed with only a keyboard.
  • When navigating with a keyboard:
    • Use the Tab key to move forward and Shift + Tab to move backward to reach the banner.
    • Press Enter or Spacebar to open and close the banner.
  • Confirm that focus is clearly visible on each interactive element.
  • Confirm that the banner does not trap focus. When you navigate with a keyboard, you can easily move into and out of the banner, regardless of whether the banner is open or closed.
  • When you navigate out of an open banner using your keyboard, it doesnā€™t automatically close.
  • The banner button is the first interactive object after the ā€œskip navigationā€ link. When you navigate your site with a keyboard and bypass the ā€œskip navigationā€ link, the "Hereā€™s how you knowā€ banner button is the first focusable item on the page.

Screen reader testing

Use a screen reader (such as NVDA, JAWS, or VoiceOver) to test the banner.

  • Screen reader announces button. When you use a screen reader and access the banner, the screen reader uses the word "button" to announce the "Hereā€™s how you know" button.
  • Screen reader announces collapsed and expanded states. When you first access the "Hereā€™s how you know" button while using a screen reader, the screen reader announces that it is "collapsed." When activated, the screen reader announces "expanded."
  • Screen reader does not announce decorative icons. When you open the banner with a screen reader, you donā€™t hear any information about the flag, blue government building, or green circled lock icon. When you view the alt text for the flag, blue government building, and green circled lock icon, you see that the alt attribute has an empty value.
  • Screen reader announces the lock icon inside the parentheses. When you open the banner with a screen reader, the screen reader uses the words "lock icon"Ć„ to announce the lock icon inside the parentheses.

From USWDS' Banner accessibility tests

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Incomplete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in Figma.
    Incomplete