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
Preact/React documentation for Storybook
Experimental Web Components
Web component documentation for Storybook
Style customization
The following CSS variables can be overridden to customize UsaBanner components:
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.
Component maturity
This component meets 90% of our maturity criteria.
Incomplete criteria
- Incomplete
Forced Colors Mode (FCM): While using FCM the components text is legible and improves readability.
What does this mean?
Each component is tested against the following items to gauge the component's maturity. When using incomplete components, consider the unmet criteria as applied to your product.
For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.
- Complete
Color: Meets AA color contrast standards for accessibility and color blindness.
- Incomplete
Forced Colors Mode (FCM): While using FCM the components text is legible and improves readability.
- Complete
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.
Accessibility
- Complete
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.
Code
- Complete
Code: Tokens implemented in code.
- Complete
Design: Tokens implemented in the Sketch.