Banner notifies users of an issue or status that affects an app, page, or section. It can be used to communicate all Forge alert types.

• Banner appears on page load or after the user takes a specific action, like submitting a form.
• It appears inline (not overlapping any content) at the top of the page or at the top of a section, if a more targeted notification is appropriate.
• Banner contains text and can include a link, usually to a page where users can learn more or resolve errors.
• Once the user has read or interacted with the content in Banner, it can be dismissed using the (optional) Close icon.

• To communicate an issue or status that affects an app, page, or section 
• To draw attention to an issue that isn’t related to a specific task 
• To confirm an event, like successfully submitting a form 

• For critical alerts or warnings that users must acknowledge 
• For frequent notifications, because too many Banners cause alert fatigue

No additional information for this component.

A page-level Banner sits below the global navigation at the top of the page and header, but not above any left-hand sidebar. Banner resizes fluidly with the page body area.  

A section-level Banner sits at the top of the relevant section’s content and spans the full width of the parent container.

Case 

Use title case for Banner heading text (“Security Update”, not “Security update”). Use sentence case for body text.  

Alert types 

Match the Banner alert type to the message content: 

• Informational (default): General tips and helpful information 
• Success: A confirmation or success message 
• Attention: An error or alert, typically asking users to take action 
  • Error messages should explain what happened and how to resolve the issue.  
• Critical: Limited use. Reserved for: 
  • Patient safety issues 
  • Other extremely important issues, like a business problem that could affect the client’s financial health 

For help writing Banner message content, see Content.

Banner content

Use the BannerItem subcomponent to implement Banner children. This ensures proper layout and spacing. All Banner features (e.g., the alert, Close icon, header text) can be customized by changing props on the Banner or BannerItem.

Closing

Banner can be set so that users can dismiss it using the Close icon, but you must implement the code that handles this action.

To do this, use the onHide prop to make the Close icon appear. The onHide prop handles whatever actions happen after the Banner is closed. Use Banner in conjunction with the ShowHide component for a smooth onClose transition.

Implementation links

Banner directory in Bitbucket

BannerItem directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook-lts.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessability in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { Banner, BannerItem } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import Banner from '@athena/forge/Banner';
import BannerItem from '@athena/forge/BannerItem';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import Banner from '@athena/forge/dist/Banner';
import BannerItem from '@athena/forge/dist/BannerItem';