@material/banner NPM

Banner

A banner displays a prominent message and related optional actions.

Content

Using banners

A banner displays an important, succinct message, and provides actions for users to address (or dismiss the banner). It requires a user action to be dismissed.

Banners should be displayed at the top of the screen, below a top app bar. They’re persistent and nonmodal, allowing the user to either ignore them or interact with them at any time. Only one banner should be shown at a time.

Installing banners

npm install @material/banner

Styles

@use "@material/banner/styles";

JavaScript instantiation

import {MDCBanner} from '@material/banner';
const banner = new MDCBanner(document.querySelector('.mdc-banner'));

See Importing the JS component for more information on how to import JavaScript.

Banners

Banner example

<div class="mdc-banner" role="banner">
  <div class="mdc-banner__content"
       role="status"
       aria-live="assertive">
    <div class="mdc-banner__text">
      There was a problem processing a transaction on your credit card.
    </div>
    <div class="mdc-banner__actions">
      <button type="button" class="mdc-button mdc-banner__primary-action">
        <div class="mdc-button__ripple"></div>
        <div class="mdc-button__label">Fix it</div>
      </button>
    </div>
  </div>
</div>

Variants

Banner with image

Images can help communicate a banner’s message.

<div class="mdc-banner" role="banner">
  <div class="mdc-banner__content"
       role="status"
       aria-live="assertive">
    <div class="mdc-banner__image" role="img" alt=""></div>
    <div class="mdc-banner__text">
      There was a problem processing a transaction on your credit card.
    </div>
    <div class="mdc-banner__actions">
      <button type="button" class="mdc-button mdc-banner__primary-action">
        <div class="mdc-button__ripple"></div>
        <div class="mdc-button__label">Fix it</div>
      </button>
    </div>
  </div>
</div>

Banner with two actions

Banners may have one or two low-emphasis text buttons.

<div class="mdc-banner" role="banner">
  <div class="mdc-banner__content"
       role="status"
       aria-live="assertive">
    <div class="mdc-banner__text">
      There was a problem processing a transaction on your credit card.
    </div>
    <div class="mdc-banner__actions">
      <button type="button" class="mdc-button mdc-banner__secondary-action">
        <div class="mdc-button__ripple"></div>
        <div class="mdc-button__label">Learn more</div>
      </button>
      <button type="button" class="mdc-button mdc-banner__primary-action">
        <div class="mdc-button__ripple"></div>
        <div class="mdc-button__label">Fix it</div>
      </button>
    </div>
  </div>
</div>

API

Sass mixins

Access to theme mixins require importing the banner's theme style module.

@use "@material/banner";

Mixin	Description
`fill-color($color)`	Sets the fill color of the banner.
`text-color($color)`	Sets the color of the banners's text.
`divider-color($color)`	Sets the color of the banner's divider.
`min-width($min-width, $mobile-breakpoint)`	Sets the `min-width` of the banner content on tablet/desktop devices. On mobile, the width is automatically set to 100%.
`max-width($max-width)`	Sets the `max-width` of the banner content.

`MDCBanner` events

Event name	`event.detail`	Description
`MDCBanner:closing`	`MDCBannerCloseEventDetail`	Indicates when the banner begins its closing animation.
`MDCBanner:closed`	`MDCBannerCloseEventDetail`	Indicates when the banner finishes its closing animation.
`MDCBanner:opening`	`{}`	Indicates when the banner begins its opening animation.
`MDCBanner:opened`	`{}`	Indicates when the banner finishes its opening animation.

`MDCBanner` Methods

Method Signature	Description
`open() => void`	Opens the banner.
`close(reason: CloseReason\|string = '') => void`	Closes the banner, optionally with the specified action indicating why it was closed.
`isOpen() => boolean`	Returns whether the banner is open.
`getText() => string`	Gets the text of the banner.
`setText(text: string) => void`	Sets the text of the banner.
`getPrimaryActionText() => string`	Gets the banner's primary action text.
`setPrimaryActionText(actionButtonText: string) => void`	Sets the banner's primary action text.
`getSecondaryActionText() => string\|null`	Gets the banner's secondary action text. Returns null if the banner has no secondary action.
`setSecondaryActionText(actionButtonText: string) => void`	Sets the banner's secondary action text.

Usage Within Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a banner for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.