esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

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.

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.

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

    Write the structure

    The message is short, so the banner needs no title. Wording itself belongs to the Microcopy and Tone lessons.

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

How is this lesson?

Last updated on 17 November 2026

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.