Banner

Banner is used to highlight important information.

v0.25.1AlphaNot reviewed for accessibility

Description

Use Banner to highlight important information.

Accessibility

Improve discoverability with a heading and landmark

Banners are made visually prominent with icons and colors to immediately draw attention.

To ensure the Banner is also easily discoverable for assistive technology users, consider:

  1. Providing a heading inside of the Banner that describes the purpose of the Banner.
  2. Designating the Banner as a region landmark. This can be achieved by rendering the Banner as a section with an aria-labelledby pointing to the heading.

Communicating feedback

When a Banner is used to communicate feedback, a live region or focus management technique should be in place to ensure that assistive technology users are aware of the feedback, especially when the Banner is shown client-side. Visit the Banner's Accessibility section, or defer to the accessibility team.

Approach 1: Announcing a Banner

A live region announcement can be used to communicate non-critical feedback, such as a success message.

To successfully trigger a live region announcement for a Banner that is un-hidden or dynamically injected onto the page, do not set the live region attribute/role on the Banner itself. Instead, it's important to rely on a live region that is already guaranteed to be on the page. Learn more about specific techniques at: Staff only: Challenges with live regions.

Approach 2: Focusing a Banner

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.

To properly focus a Banner, add a tabindex="-1" place focus with JavaScript (using the focus() API).

Arguments

NameDefaultDescription
tag

:div

Symbol

One of :div or :section.

full

false

Boolean

Whether the component should take up the full width of the screen.

full_when_narrow

false

Boolean

Whether the component should take up the full width of the screen when rendered inside smaller viewports.

dismiss_scheme

:none

Symbol

Whether the component can be dismissed with an "x" button. One of :hide, :none, or :remove.

dismiss_label

Dismiss

String

The aria-label text of the dismiss "x" button

description

nil

String

Description text rendered underneath the message.

icon

nil

Symbol

The name of an Octicons icon to use. If no icon is provided, a default one will be chosen based on the scheme.

scheme

:default

Symbol

One of :danger, :default, :success, or :warning.

system_arguments

N/A

Hash

Examples

Slots

action

A button or custom content that will render on the right-hand side of the component.

To render a button, call the with_action_button method, which accepts the arguments accepted by Button.

To render custom content, call the with_action_content method and pass a block that returns HTML.