Sections

Banners

Banners are a type of notice, delivering both system and engagement messaging. These are highly intrusive messaging methods and so should be used appropriately.

System banners are used for system messaging. They are full-width notices placed in one of two locations:

Above everything else: If the system banner is related to the entire website (e.g. the website is in read-only), place the banner first. These cannot be dismissed until the issue is resolved. To pin a system banner to the top of the browser window, add .is-pinned.
Below the top navigation bar: This is the default location for all system banners. Use these banners when it affects only a particular area of the product (e.g. when a product subscription is about to expire).

Since system banners are a type of notice, you can use the following notice visual styles in conjunction with .s-banner:

Classes

Section titled Classes

Class	Applies to	Description
`.s-banner`	N/A	Base banner parent class. This defaults to a system banner style.
`.s-banner--btn`	`.s-banner`	Child element applied to .s-btn within a banner to give it a subtle tint that’s appropriate in that context.
`.s-banner__info`	`.s-banner`	Applies info (blue) visual styles.
`.s-banner__success`	`.s-banner`	Applies success (green) visual styles.
`.s-banner__warning`	`.s-banner`	Applies warning (yellow) visual styles.
`.s-banner__danger`	`.s-banner`	Applies danger (red) visual styles.
`.s-banner__important`	`.s-banner`	Emboldens the above visual styles by strengthening the background saturation. This should be used for time-sensitive, pressing information that needs to be noticed by the user.

JavaScript

Section titled JavaScript

The .s-banner component includes a controller to show and hide the banner programitically. While it is optional, at least including the functionality to close the banner is recommended.

Attributes

Section titled Attributes

Attribute	Applied to	Description
`data-controller="s-banner"`	Controller element	Wires up the element to the banner controller. This may be a `.s-banner` element or a wrapper element.
`data-s-banner-target="banner"`	.s-banner element	Wires up the element that is to be shown/hidden
`data-s-banner-remove-when-hidden="true"`	Controller element	Optional Removes the banner from the DOM entirely when it is hidden

Events

Section titled Events

Event	Element	Description
`s-banner:show`	Banner target	Default preventable Fires immediately before showing the banner. Calling `.preventDefault()` cancels the display of the banner.
`s-banner:shown`	Banner target	Fires after the banner has been visually shown
`s-banner:hide`	Banner target	Default preventable Fires immediately before hiding the banner. Calling `.preventDefault()` cancels the removal of the banner.
`s-banner:hidden`	Banner target	Fires after the banner has been visually hidden

event.detail	Applicable events	Description
`dispatcher`	`s-banner:*`	Contains the `Element` that initiated the event. For instance, the button clicked to show, the element clicked outside the banner that caused it to hide, etc.

Helpers

Section titled Helpers

Function	Parameters	Description
`Stacks.showBanner`	`element`: the element the `data-controller="s-banner"` attribute is on	Helper to manually show an s-banner element via external JS
`Stacks.hideBanner`	`element`: the element the `data-controller="s-banner"` attribute is on	Helper to manually hide an s-banner element via external JS

Examples

Section titled Examples

Style

Important?

Pinned?

Info

Section titled Info

<div class="s-banner s-banner__info" role="alert" aria-hidden="false">…</div>
<div class="s-banner s-banner__info s-banner__important" role="alert" aria-hidden="false">…</div>

Success

Section titled Success

<div class="s-banner s-banner__success" role="alert" aria-hidden="false">…</div>
<div class="s-banner s-banner__success s-banner__important" role="alert" aria-hidden="false">…</div>

Warning

Section titled Warning

<div class="s-banner s-banner__warning" role="alert" aria-hidden="false">…</div>
<div class="s-banner s-banner__warning s-banner__important" role="alert" aria-hidden="false">…</div>

Danger

Section titled Danger

<div class="s-banner s-banner__danger" role="alert" aria-hidden="false">…</div>
    <div class="s-banner s-banner__danger s-banner__important" role="alert" aria-hidden="false">…</div>

JavaScript Example

Section titled JavaScript Example

<div
    role="alert"
    id="example-banner"
    class="s-banner"
    aria-labelledby="example-message"
    aria-hidden="true"
    data-controller="s-banner"
    data-s-banner-target="banner">
    Example banner
</div>
…
<button
    data-toggle="s-banner"
    data-target="#example-banner">
    Show banner
</button>

document.querySelector(".js-banner-toggle").addEventListener("click", function(e) {
    Stacks.showBanner(document.querySelector("#example-banner"));
});