Banner

Usage

Banner can be used in one of two ways:

1. To highlight prominent information on a page.
2. To communicate feedback in response to a user action.

For system wide information, consider using an announcement.

Best practices

Use banners sparingly and only when necessary. Banners can disrupt the user experience and should only be used when and where relevant.

Keep the message concise and direct. Don't use heading styling or multiple type sizes in banners, rely on the default paragraph size and use the title when appropriate.

Don't show more than one banner at a time. For more information, see this article on alert fatigue.

Anatomy

Options

Variant

Critical

Use critical banners to signal critical errors, system failures, or necessary destructive actions. Examples: form validation error summary, repo deletion confirmations.

Warning

Use warning banners to alert users about potential issues or impactful changes. For example possible connectivity concerns or hidden items due to active filters.

Success

Use success banners to indicate task completion or successful actions. For example, a successful issue transfer when the user is not brought to the new page. Only use success messages if the success is not easily apparent in the UI.

Info

Use info banners to inform about non-critical context and information. For example feature prompts or ongoing processes.

Upsell

Use upsell banners to inform the users about a feature that can be enabled by upgrading their plan.

Title

Use a title to concisely present the topic of the banner when the message of the banner is complex and too long to scan.

A title is required and will be used as a semantic page heading. However, you can visually hide the title. It is recommended to hide the title if the body of the banner is short and easily scannable.

Use the built-in accessibility annotations in the Figma components to define the heading level and text relevant to its context.

Dismissable

Dismiss button

Banners with an onDismiss property automatically show a dismiss button. This should be used for banners that inform about something that the user can not solve. For example issues with the organization they are part of or informational banners. When it makes sense, the choice to dismiss the banner should be stored and the banner should not be shown again.

Use the following as a guideline:

• If you're on a page in which you can do other tasks, and the banner is not blocking / does not have to be addressed, then you should be able to have a close button.
• If accidental closure of the banner would leave the user confused or missing something critical, it should not have a close button.

Exception: Critical banner

Critical banners can't be dismissable. They are mostly used for errors which need to be resolved. As a result you can only get rid of a critical banner by resolving the error. If used to warn about destructive actions, the banner should also not be dismissable.

If the error must be resolved on a different page, use an action that directs the user to the page where the error can be resolved.

Actions

A maximum of 2 actions can be added to a banner. Whenever possible it is recommended to only add a single action to better direct the users attention.

For banners with a single action, you can choose between adding a primary or secondary action depending on how much attention you want to draw to the action.

For banners with two actions, one of them must be primary and the other must be secondary. In this case, use the primary action for the recommended action. For example, the primary action enables a feature and the secondary action links more information.

Icon

The icon relates to the selected variant and can't be disabled. It can only be changed for banners of variant info or upsell.

Layouts

The internal banner layout changes for large banners depending on its content.

1. Banners with a single line of content have the actions and the dismiss button in the same line to keep them compact.
2. If you add a title to the banner, the dismiss button will be aligned in the top right corner
3. Banners with a title but no dismiss button will have the actions aligned to the top right corner
4. A banner with a title, a dismiss button and one or two actions has the dismiss button aligned to the top right corner and the actions below the content aligned to the left

Responsive Design

On large screens the layout of the elements within the banner adjust depending on which elements are enabled. On small screens the banner always uses the stacked layout.

Position

A banner should always be positioned as close to the section it relates to as possible.

If a banner informs about something that relates to the current page, it should be placed above the pages headline. However, if the banner is only relevant to a portion of the page place it above the section it relates to.

In dialogs banners are normally placed above the content just below the dialogs header. Since a dialog is normally small it can be compared to a section.

Accessibility

Feedback Banners

Banners that are used to communicate feedback require extra accessibility considerations to ensure they are surfaced immediately to all users including those using assistive technologies. This relates to WCAG 4.1.3 Status Messages.

Example scenarios that require extra considerations include:

• When a user submits a form, an error banner is shown with a list of form errors that need to be corrected.
• When a user submits a form, the submission successfully goes through and a success banner is shown.
• When a user saves a setting, an error banner is shown to communicate that an unexpected error has occured and the setting was not saved.
• When a user toggles an option, a warning banner is shown to warn the user of potential consequences.

Banners used in these scenarios can be made more accessible through either a focus management or a live region announcement technique:

• Focus management would involve moving focus to the newly shown Banner. This is the most reliable way to ensure that a user is aware of the new content. This is the preferred method for critical Banner scenarios (with exceptions).
• Live region announcements: A live region announcement can be used to announce the new content to screen reader users. This method is less reliable than focus management, but may be the preferred method for non-critical information (with exceptions).

Here are some questions to consider when deciding which method to use:

How critical is the information?

Critical information (such as an error) should be made as discoverable as possible. Though moving focus to the Banner can be considered more disruptive than a live region announcement, it's more important that a user is able to discover the Banner so they can take an appropriate action. In most critical scenarios, using focus management is the best approach.

On the other hand, for communicating newly shown non-critical information (such as a success), a live region announcement is sufficient in most scenarios. A live region announcement can sometimes fail to fire and can easily be missed, so it should be reserved for use on non-critical information where there are no consequences if a user misses it.

Where is a user's focus when the banner appears?

If an action triggers updates to the UI resulting in a user's focus getting lost and a new Banner being shown, place focus on this newly shown Banner instead of using a live region announcement.

For example, let's say that a user activates a "Submit" button. Upon doing so, significant portions of the UI (including this button) gets removed and replaced by a success banner. The fact that this is a non-critical banner may lead us to think announcing the banner is sufficient. However, given that the user experiences focus loss as a result of the control they were on being removed from the page, focus management is more appropriate.

This is because focus loss can result in some screen reader users being taken back to the top of the page and be disorienting. This is a WCAG 2.4.3 Focus Order issue.

Does the Banner contain an action?

If the Banner contains an action, placing focus on the newly shown Banner is preferred over a live region announcement so that a screen reader user can immediately interact with the action without having to manually locate it.

Is there already a live region on the page that can be utilized?

Dynamic live regions can have some challenges (GitHub Staff Only), so this method requires ample testing.

Please reach out to the accessibility team if you need help determining the best approach for your use case!

Known accessibility issues (GitHub staff only)