# @material/banner
> The Material Components Web banner component.
Latest version **14.0.0** (published 2022-04-28) · MIT license · 0 weekly downloads
## Install
```sh
npm install @material/banner
pnpm add @material/banner
yarn add @material/banner
bun add @material/banner
```
## Health
**Score 20/100 (F)** — status: abandoned.
Positive: esm support; no vulnerabilities.
Warnings: low downloads; no types.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 14.0.0 |
| Published | 2022-04-28 |
| First published | 2020-08-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 12 |
| Unpacked size | 448.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | yefim, abhiomkar, azakus, bicknellr, material-admin, aprigogin, patrickrodee, aomarks, emarquez, allanchen, esgonzalez, asyncliz, candysonya, ssuarez, taylorv |
| Keywords | material components, material design, banner |
## Links
- npm: https://www.npmjs.com/package/@material/banner
- Repository: https://github.com/material-components/material-components-web
- Homepage: https://github.com/material-components/material-components-web#readme
- Issues: https://github.com/material-components/material-components-web/issues
- npm.io page: https://npm.io/package/@material/banner
## Dependencies (12)
- [tslib](https://npm.io/package/tslib.md) ^2.1.0
- [@material/dom](https://npm.io/package/@material/dom.md) ^14.0.0
- [@material/rtl](https://npm.io/package/@material/rtl.md) ^14.0.0
- [@material/base](https://npm.io/package/@material/base.md) ^14.0.0
- [@material/shape](https://npm.io/package/@material/shape.md) ^14.0.0
- [@material/theme](https://npm.io/package/@material/theme.md) ^14.0.0
- [@material/button](https://npm.io/package/@material/button.md) ^14.0.0
- [@material/ripple](https://npm.io/package/@material/ripple.md) ^14.0.0
- [@material/tokens](https://npm.io/package/@material/tokens.md) ^14.0.0
- [@material/elevation](https://npm.io/package/@material/elevation.md) ^14.0.0
- [@material/typography](https://npm.io/package/@material/typography.md) ^14.0.0
- [@material/feature-targeting](https://npm.io/package/@material/feature-targeting.md) ^14.0.0
## Recent versions
- 14.0.0 (latest) — 2022-04-28
- 15.0.0-canary.423edc3dc.0 (canary) — 2024-06-26
- 12.0.0-nightly.778a0e8a.0 (nightly) — 2021-07-20
- 15.0.0-canary.cfec83c74.0 — 2024-05-20
- 15.0.0-canary.2f5b899bc.0 — 2024-05-20
- 15.0.0-canary.f80ac92b0.0 — 2024-05-02
- 15.0.0-canary.4b35cb7d0.0 — 2024-05-02
- 15.0.0-canary.65c10a622.0 — 2024-04-25
- 15.0.0-canary.311f29a60.0 — 2024-04-23
- 15.0.0-canary.5bebc0064.0 — 2024-04-11
- 15.0.0-canary.68edc03c6.0 — 2024-04-08
- 15.0.0-canary.453a6248a.0 — 2024-03-25
- 15.0.0-canary.819498d8c.0 — 2024-03-15
- 15.0.0-canary.c43b3438b.0 — 2024-02-23
- 15.0.0-canary.e50b478eb.0 — 2024-02-08
- … 1096 more at https://npm.io/package/@material/banner/versions
## README
# Banner
A banner displays a prominent message and related optional actions.
**Contents**
* [Using banners](#using-banners)
* [Banners](#banners)
* [API](#api)
* [Usage within web frameworks](#usage-within-web-frameworks)
## 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
```scss
@use "@material/banner/styles";
```
### JavaScript instantiation
```js
import {MDCBanner} from '@material/banner';
const banner = new MDCBanner(document.querySelector('.mdc-banner'));
```
> See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
## Banners
### Banner example
```html
There was a problem processing a transaction on your credit card.
```
### Variants
#### Centered
By default, banners are positioned as leading.
They can optionally be displayed centered by adding the `mdc-banner--centered` modifier class to the root element:
```html
...
```
Alternatively, you can call the `position-centered` mixin from Sass:
```scss
.my-banner {
@include banner.position-centered;
}
```
#### Fixed banner
When used below top app bars, banners should remain fixed at the top of the screen. This can be done by adding the `mdc-banner__fixed` wrapper element around the content element:
```html
There was a problem processing a transaction on your credit card.
```
#### Banner with graphic
Images can help communicate a banner’s message.
```html
error_outline
There was a problem processing a transaction on your credit card.
```
#### Banner with two actions
Banners may have one or two low-emphasis text buttons.
```html
There was a problem processing a transaction on your credit card.
```
#### Mobile stacked
On mobile view, banners with long text should have their action(s) be positioned _below_ the text instead of alongside it. This can be accomplished by adding the `mdc-banner--mobile-stacked` modifier class to the root element:
```html
...
```
Alternatively, banner can be in stacked layout regardless of mobile-breakpoint, with the `layout-stacked` mixin from Sass:
```scss
.my-banner {
@include banner-theme.layout-stacked;
}
```
## API
### Sass mixins
Access to theme mixins require importing the banner's theme style module.
```scss
@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.
`position-centered()` | Sets the banner content to centered instead of leading.
`z-index($z-index)` | Sets the z-index of the banner.
### `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` properties and methods
Property | Value Type | Description
--- | --- | ---
`isOpen` | `boolean` (read-only) | Returns whether the banner is open.
Method Signature | Description
--- | ---
`open() => void` | Opens the banner.
`close(reason: CloseReason) => void` | Closes the banner, with the specified action indicating why it was closed.
`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.
`layout() => void` | Recalculates layout. With height being calculated dynamically recommended to call on window `resize` events.
### 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](../../docs/integrating-into-frameworks.md).
See [MDCBannerAdapter](./adapter.ts) and [MDCBannerFoundation](./foundation.ts) for up-to-date code documentation of banner foundation APIs.
---
_Source: https://npm.io/package/@material/banner · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._