Banner: Build One Reusable Top-of-Page Strip With Clear Variants and Rules
A banner is a shared top-of-page message. Learn when to use it, how to build its parts and variants, and how to make it work for everyone.
In short
A banner is a shared top-of-page message strip in a design system, built once with clear parts and variants and made to work for everyone.
13 min readFree
What you will learn
Some messages are too important to slip past a reader, yet too general to block the whole screen. A banner fits that gap. In this lesson you will learn what a banner is, when it beats a toast or a modal, how to build its parts and variants once, and how to make it work for people who use screen readers, keyboards, and small phones. We will walk through a GitHub-style banner step by step, then check your thinking with a short quiz.
Key words
- Banner
- A wide message strip at the top of a page or section. It stays until the user acts or the message stops being true.
- Variant
- One version of the same component for a different meaning, such as info or error.
- Semantic type
- The meaning a variant carries, so people and tools know what kind of message they are reading.
- Toast
- A small message that appears briefly and, when it has no actions, disappears on its own.
- Modal
- A window that blocks the rest of the screen until the user answers it.
- Inline message
- A short note placed right next to the thing it describes, such as under a form field.
- Persistent
- Stays on screen until something ends it.
- Dismiss control
- The close button that lets a user hide a message.
- Screen reader
- Software that reads page content aloud for people who cannot see it well.
- ARIA role
- A label that tells a screen reader what kind of content something is, such as an urgent alert or a calm status update.
How do urgency and persistence decide the pattern?
Toast
Toasts without actions can disappear automatically or be dismissed by the user. A success message that floats above the interface and auto-dismisses is a toast, not a banner. Use toasts for quick confirmations.
Banner
Use it for a status that stays true for a while, such as an outage. A banner suits a persistent status that stays true until it is resolved, like an outage.
Modal
A modal blocks the page until the user answers. If a message is critical enough to halt all interaction, use a modal.
Inline message
A note placed beside the part it describes. Banners work best for general notifications for the product or system, not a specific task.
A common mistake is using a banner for a form error.
Tip
Ask two questions. Would the user miss this if it vanished quickly? Must they act before continuing? A no to the first points to a toast. A yes to the second points to a modal, or to a banner that stays until fixed.
What is the anatomy of a banner?
Anatomy means the named parts of a component. Learn these names first, because later rules refer to them. GitHub's Primer guidance lists the message, title, icon, dismiss button, and primary and secondary actions as the parts of a banner.
Icon
A small symbol that shows the variant at a glance. Icons match the banner variant and can't be disabled, but custom icons can be used for info and upsell.
Title and message
The message carries the detail. Add a title only when the message is too long to scan. The title names the topic in a few words.
Action
An optional button or link for the next step. A banner can persist until dismissed and may include a link or a quiet button.
Dismiss control
The close button, often an X, that hides the banner. Primer's component can take a dismiss setting that renders an X button.
Button styles are covered in the Buttons lesson. Here, focus on the banner's own parts.
What are the semantic variants of a banner?
A variant is one version of the same component for a different meaning. Most teams build four: info, success, warning, and error. The colors for each are set in the Functional Colors lesson. Here, focus on what each meaning tells the user.
Info
Neutral news that helps the user, such as a new policy or a planned change. Nothing has broken.
Success
A good outcome worth seeing for a moment. Success Banner has its standard circle and check icon.
Warning
Something needs attention soon, but the product still works. The user can choose when to act.
Error
Something failed and must be fixed. Critical banners communicate an error which the user must resolve in order for the banner to disappear.
What are the placement and stacking rules?
Placement decides whether anyone sees the banner. Stacking means what happens when more than one message wants the top of the page. Write these rules into the component, so no team has to guess.
One at a time
Do not display more than one banner on a single page at the same time. Carbon gives the same rule.
Top of the page
Place system-wide messages directly below the main header or navigation bar. BC Government's guidance also places it immediately above or below the header.
Do not cover content
The banner should push content down, not sit over buttons or text. Do not cover other content with a banner notification.
Match the width
Make sure the alert banner is the same length as the other components on the screen.
Match the section
When the message is about one section, banners should be placed at the top of the content area they relate to.
Dismissal is a design decision that you document, not a default. Use these rules as a starting point, then have your team confirm them.
Notices
When it makes sense, the choice to dismiss the banner should be stored and the banner should not be shown again.
Failed actions
In certain cases, the banner may be dismissible when notifying the user of a failed action.
Destructive warnings
If used to warn about destructive actions, the banner should also not be dismissible.
Auto-hiding banners
If a banner auto-dismisses, it should be treated with the same design constraints as a toast; it must be low-urgency, it must not contain critical information the user needs to act on.
Worked example: a GitHub-style banner, step by step
GitHub publishes guidance for its Banner component through Primer, its design system. The steps below show how those rules turn one message into a reusable component. The payment scenario is our own illustration. It is not a copy of a real GitHub notice. For scope, system announcements related to a specific product area, such as a single sign-on message, should use the Banner component.
- 1
Confirm the pattern
A failed card payment on a billing page is a message about one product area. That fits a banner at the top of the billing page, not a modal.
- 2
Pick the variant
A failed payment blocks the account, so it is an error. The icon and color follow the error variant. The designer does not pick the icon freely, because it must match the variant.
- 3
Write the structure
The message is short, so the banner needs no title. Wording itself belongs to the Microcopy and Tone lessons.
- 4
Set the actions
One primary action, such as 'Update card', is enough. A second link to billing history stays within the two-action limit.
- 5
Decide dismissal
The account cannot keep working until the card is fixed, so the banner is critical. It stays until the payment succeeds, and its close control is turned off.
- 6
Place it
Show it alone at the top of the billing page. A feature announcement waits for a later visit instead of stacking beneath it.
- 7
Check the narrow view
On a phone, the icon, wrapped text, and close control share the first row, and the action drops to a second row. Primer shows this layout for a narrower banner.
- 8
Document it
Record the decisions as rules: variants, parts, dismissal, placement, and accessibility checks. The next team can then reuse the banner without asking you.
A component is reusable only when its rules are written down. A good banner page lists the items below, and every new banner should pass each one.
Variants
Info, success, warning, and error, each with its meaning and icon rule.
Parts
Which parts are required, such as the message and the dismiss rule, and which are optional, such as the title and actions.
Limits
One banner per page, and at most two actions.
Accessibility
The urgency level and matching role, contrast checks, keyboard use, and narrow-screen layout.
Make banners accessible and robust
A banner helps only if people can notice it, read it, and act on it. Some users cannot see the strip, some move only with a keyboard, and some hear it through a screen reader. This lesson covers banner rules. General accessibility principles are in the Accessibility lesson.
Choose status or alert by urgency
A screen reader needs to know how urgent a message is. Designers choose the urgency level, and builders attach the matching ARIA role. Hennepin County explains that the role tells assistive technology how urgent the banner message is.
Alert
For messages that cannot wait. Default to status, and promote a message to alert only when it genuinely cannot wait: a failed submission, a lost connection, a session about to time out.
Status
For important but calm news, such as saved settings or a finished sync. role=status for important but non-urgent information.
Region
For general information and updates that are not urgent. Hennepin County lists this role for highlighting general updates.
Tip
Use alert sparingly. Save role alert for truly urgent messages. For regular updates, use role status or a polite live setting. Some teams attach the role to the message container, not to the button that opens it.
Color, contrast, and keyboard use
Never color alone
A banner's meaning must not depend only on color. Variant themes use both colour and icons to communicate an alert's type.
Enough contrast
The text and background must contrast enough to read. Make sure that the combination of background and foreground guarantees compliance with WCAG contrast guidelines. WCAG is the main web accessibility standard.
Keyboard reach
A keyboard user must be able to reach the action and the close control. Use a real button element with an accessible name such as Dismiss notification, and hide the decorative glyph from assistive technology.
No disabled buttons
No buttons should be disabled within an Alert. A disabled control confuses people who cannot tell why it is unavailable.
Focus for critical errors
For a critical error with an action, focusing the banner can be appropriate for critical feedback scenarios, such as a form validation error summary where the banner contains actions to help unblock the user. Use this sparingly.
Behavior on small screens
A wide strip can crowd a phone. The message and the close control must stay visible without hiding page content. BC Government's guidance says content should reflow as the screen narrows, so that nothing is lost. Content reflows as viewport size decreases.
Tip
Test with the longest message your team might write, at the narrowest width your product supports. The banner should grow taller rather than push the page header off screen.
Common mistakes to avoid
Permanent content
Avoid banners for permanent page content; put that in the page header or a section instead.
Long text
If more detail is needed, provide a link or CTA to a dedicated page or modal, rather than extending the banner body.
Ignored strips
Too many banners teach people to skip them.
Check yourself
Each scenario needs the rules above. Pick the best answer.
Quick check
Your app must tell a customer that a subscription payment failed and that they must update their card. A separate 'new feature available' note also needs to show. Which setup fits the rules?
Quick check
Your team plans a maintenance window for next Sunday night. The notice is for every user, is important, but blocks nothing today. Which setup should you write down?
Quick check
A banner warns that a user's session will end in two minutes unless they choose to stay signed in. Which ARIA role should the banner use?
Key takeaways
A banner is a shared, persistent strip for news or a problem that stays true until it is resolved. Build it once with four clear variants, write its dismiss, placement, and action rules down, and choose its role by urgency. Test it on a small screen and with a keyboard before any team reuses it.
Sources
- Primer (GitHub design system): Banner guidelines
- Primer (GitHub design system): Notification messaging
- Primer: Banner Rails component documentation
- Primer: CTA banner guidelines
- Carbon Design System: Notifications pattern
- Carbon Design System: Notification pattern (earlier page)
- British Columbia Government Design System: Alert banner
- Hennepin County Design System: Alert banner
- VA.gov Design System: Alert
- W3C: WAI-ARIA 1.3 specification
- accessibility.build: Accessible notifications and toasts guide
- A11Y Collective: How to use ARIA alert effectively
- Baymard Institute: What is a banner UI element
- UserTourKit: What is an in-app banner
- Setproduct: Notifications UI design
- Mobbin glossary: Banner UI design
Last updated on 17 November 2026
Related lessons
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.