# 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.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/banner

## 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.

- **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.

## What is a banner in a design system?

In a design system, a banner is a core component. Designers and builders make it once and document it, and every product team reuses it. Some teams call the same pattern a callout, an alert bar, or a notification bar. Banners are sometimes called callouts, alert bars, notification bars, or info banners, depending on the platform and design system.

A banner runs across the top of the page or a section. It is a non-blocking strip that communicates information without interrupting the current task. It persists until the user dismisses it or the display condition expires. Unlike toasts, it does not disappear on a timer.

Banners suit news for a whole product or system, such as a service problem. They take over the top of an interface to show general notifications for the product or system, not a specific task.

## Banner or another message type?

Choose the pattern by asking two questions. First, how urgent is the message? Must the user act before going on? Second, how long should it last? Should it fade by itself, or wait until someone deals with it? Your answers point to one pattern.

### 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?

A. Show both as banners, one above the other, so nothing is missed.
B. Show the payment failure as a toast that fades after a few seconds, and show the new feature as a banner.
C. Show the payment failure as an error banner that stays until the card is updated, and hold the feature note for a later, non-blocking place.
D. Show the payment failure as a dismissible info banner, and the feature note as a modal so the user sees it first.

**Answer:** C. The failed payment is urgent and must be fixed, so it is an error banner that stays until resolved. Only one banner should show at a time, so the feature note waits.

**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?

A. A modal that every user must acknowledge before using the site.
B. A dismissible info or warning banner at the top of the page, announced with the status role.
C. A toast that fades after a few seconds, so it does not clutter the page.
D. An error banner that cannot be dismissed until maintenance ends.

**Answer:** B. The notice matters, but nothing is broken yet. A dismissible banner with a calm announcement suits it. A toast is too brief, and a modal blocks people for something still in the future.

**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?

A. Status, because it is a calm update.
B. Alert, because the message cannot wait.
C. Region, because it highlights general information.
D. No role, because the banner was already on the page when it loaded.

**Answer:** B. A session about to end is urgent, so it needs the alert role. A status role would wait its turn, which is too slow for this message.

## 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](https://primer-docs-preview.github.com/product/components/banner/guidelines/)
- [Primer (GitHub design system): Notification messaging](https://primer.style/product/ui-patterns/notification-messaging/)
- [Primer: Banner Rails component documentation](https://primer.style/product/getting-started/rails/components/banner/)
- [Primer: CTA banner guidelines](https://primer.github.io/brand/components/CTABanner/)
- [Carbon Design System: Notifications pattern](https://www.carbondesignsystem.com/building-blocks/core/patterns/notifications)
- [Carbon Design System: Notification pattern (earlier page)](https://carbondesignsystem.com/patterns/notification-pattern/)
- [British Columbia Government Design System: Alert banner](https://www2.gov.bc.ca/gov/content/digital/design-system/components/alert-banner)
- [Hennepin County Design System: Alert banner](https://www.hennepincounty.gov/design-system/components/components-library/alert-banner)
- [VA.gov Design System: Alert](https://design.va.gov/components/alert/)
- [W3C: WAI-ARIA 1.3 specification](https://w3c.github.io/aria/)
- [accessibility.build: Accessible notifications and toasts guide](https://accessibility.build/guides/accessible-notifications)
- [A11Y Collective: How to use ARIA alert effectively](https://www.a11y-collective.com/blog/aria-alert/)
- [Baymard Institute: What is a banner UI element](https://baymard.com/blog/banner-ui)
- [UserTourKit: What is an in-app banner](https://usertourkit.com/blog/what-is-in-app-banner)
- [Setproduct: Notifications UI design](https://www.setproduct.com/blog/notifications-ui-design)
- [Mobbin glossary: Banner UI design](https://mobbin.com/glossary/banner)
