Banner

readyNot reviewed for a11y

This page may be removed. Primer plans to move all Rails component documentation to Lookbook.

Description

Use Banner to highlight important information.

Events

Name	Type	Bubbles	Cancelable
`dismiss`	`CustomEvent<void>`	No	No

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:

Providing a heading inside of the Banner that describes the purpose of the Banner.
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.

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.

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.

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

Name	Required	Description
tag		`Symbol` One of `:div` or `:section`.
full		`Boolean` Whether the component should take up the full width of the screen.
full_when_narrow		`Boolean` Whether the component should take up the full width of the screen when rendered inside smaller viewports.
dismiss_scheme		`Symbol` Whether the component can be dismissed with an "x" button. One of `:hide`, `:none`, or `:remove`.
dismiss_label		`String` The aria-label text of the dismiss "x" button
description		`String` Description text rendered underneath the message.
icon		`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		`Symbol` One of `:danger`, `:default`, `:success`, or `:warning`.
system_arguments		`Hash` System arguments

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 Primer::Beta::Button.

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