Skip to main content

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:

  1. 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.
  2. 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:

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.

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.

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
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.
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
<div class="s-banner" role="alert" aria-hidden="false"></div>
<div class="s-banner s-banner__important" role="alert" aria-hidden="false"></div>
<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>
<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>
<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>
<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>
<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"));
});
Deploys by Netlify