The Ignite UI for Angular Banner Component provides a way to easily display a prominent message to your application's users in a way that is less transient than a snackbar and less obtrusive than a dialog. The Banner can also be configured to display custom action buttons and an icon.

Usage

To get started with the Banner component, first you need to install Ignite UI for Angular by typing the following command:

ng add igniteui-angular

For a complete introduction to the Ignite UI for Angular, read the getting started topic.

The next step is to import the IgxBannerModule in our app.module.ts file:

// app.module.ts

...
import { IgxBannerModule } from 'igniteui-angular';

@NgModule({
    ...
    imports: [..., IgxBannerModule],
    ...
})
export class AppModule {}

Basic banner

In order to display the Banner component, use its open() method and call it on a button click. To configure the banner message, simply pass some text inside of the banner content. The text will show up in the specified banner area and the banner will use its default template when displaying it

<!--banner.component.html-->

<igx-banner #connectionBanner>
    You are currently offline.
</igx-banner>
...
<button igxButton="raised" (click)="connectionBanner.toggle()">Toggle Banner</button>

The banner appears relative to where the element was inserted in the page template, moving all other content. The banner typically shows some non-intrusive content that requires minimal user interaction to be dismissed (e.g. 1-2 clicks).

Basic Banner Demo

Templating the banner

The IgxBannerComponent allows easily templating of its content while still sticking as closely as possible to the material design banner guidelines.

Changing the banner message

Changing the message displayed in the banner is easy - just change the content you are passing to the igx-banner tag. Below, we will change the content of our Connection banner to a be a bit more descriptive:

    <!--banner.component.html-->
    <igx-banner #connectionBanner>
        You have lost connection to the internet. This app is offline.
    </igx-banner>
    ...
    <button igxButton="raised" (click)="connectionBanner.toggle()">Toggle Banner</button>

Adding an icon

Developers can pass an igx-icon in the banner's content and it will always be positioned at the beginning of the banner message.

Note

If several igx-icon elements are inserted as direct descendants of the banner, the banner will try positioning all of them at the beginning. It is strongly advised to only pass one igx-icon directly to the banner. If you want to use icons in your banner message, wrap them in a span tag.

To pass an igx-icon to you banner, simply insert it in the igx-banners content:

    <!--banner.component.html-->
    <igx-banner #connectionBanner>
        <igx-icon>signal_wifi_off</igx-icon>
        You have lost connection to the internet. This app is offline.
    </igx-banner>
    ...

Adding custom banner buttons

The IgxBannerModule also exposes a directive for templating the banner buttons - IgxBannerActionsDirective. Using this directive allows you to override the default banner button (Dismiss) and add user defined custom actions. As most (but not all) of the button interactions are suposed to close the banner, make sure to call the banner's close() method in their click handlers.

Note

Per Google's Material Design guidelines, a banner should have a maximum of 2 buttons present. The IgxBannerComponent does not explicitly limit developers from passing more than 2 elements under the igx-banner-actions tag, but it is strongly advised if you choose to adhere to the material design guidelines.

To further template the 'Connection' banner, we can pass custom action handles using the igx-banner-actions selector:

    <!--banner.component.html-->
    <igx-banner #connectionBanner>
        <igx-icon>signal_wifi_off</igx-icon>
        You have lost connection to the internet. This app is offline.
        <igx-banner-actions>
            <button igxButton igxRipple (click)="connectionBanner.close()">Continue Offline</button>
            <button igxButton igxRipple (click)="wifiState = true">Turn On Wifi</button>
        </igx-banner-actions>
    </igx-banner>
    ...

The dismiss option ('Continue Offline') does not require any further logic, so it can just call connectionBanner.close(). The confirm action ('Turn On Wifi') requires some additional logic, so we define it in the component. We create and subscribe to the onNetworkStateChange Observable and on each change we call the refreshBanner method, which toggles the banner depending on wifiState.

// banner.component.ts
import { Component, OnInit, OnDestroy, ViewChild } from "@angular/core";
import { IgxBannerComponent } from 'igniteui-angular'
...
export class MyBannerComponent implements OnInit, OnDestroy {
    @ViewChild(IgxBannerComponent) public banner: IgxBannerComponent;
    public onNetworkStateChange = new Subject(); // Emits when WiFi state is changed
    private _wifiState = false;
    public get wifiState(): boolean {
        return this._wifiState;
    }
    public set wifiState(v: boolean) {
        this._wifiState = v;
        this.onNetworkStateChange.next();
    }
    ...
    public ngOnInit() { // subscribe to the event;
        this.banner.open();
        this.onNetworkStateChange.subscribe(() => this.refreshBanner()); // call change handler
    }

    public ngOnDestroy(): void { // unsubscribe
        this.onNetworkStateChange.complete();
    }
    ...
    // Define change handler
    public refreshBanner() {
        if (!this.wifiState) {
            this.banner.open();
        } else {
            if (!this.banner.collapsed) {
                this.banner.close();
            }
        }
    }
}

As the subscription fires on any change to wifiState, the banner can now also be toggled using the WiFi icon in the demo navbar.

The results of the templated banner can be seen in the below demo:

Templating Demo

Applying custom animations

The banner component also exposes an Input property that allows setting custom opening and closing animations in the animationSettings. Developers can pass custom animations - either self-defined, or those from our IgniteUI for Angular animation suite. The default animations used by the banner are growVerIn for entry and growVerOut for exiting.

Let's change the animations that our banner uses, so that it slides in.

<!--banner.component.html-->
    <igx-banner #connectionBanner [animationSettings]="animationSettings">
        ...
    </igx-banner>
    ...

// banner.component.ts
import { IgxBannerComponent, slideInLeft, slideOutRight } from 'igniteui-angular'
...
export class MyBannerComponent {
    ...
    public animationSettings = {
        openAnimation: slideInLeft,
        closeAnimation: slideOutRight
    }
    ...
}

Animation Demo

Binding to events

The banner component emits events when changing its state - onOpening and onOpened are called when the banner is shown (before and after, resp.), while onClosing and onClosed are emitted when the banner is closed. The ing events (onOpening, onClosing) are cancelable - they use the ICancelEventArgs interface and the emitted object has a cancel property. If the cancel property is set to true, the corresponding end action and event will not be triggered - e.g. if we cancel onOpening, the banner's open method will not finish and the banner will not be shown.

To cancel an event bind it to the emitted object and set its cancel property to true.

<!--banner.component.html-->
    <igx-banner #connectionBanner (onOpening)="handleOpen($event)">
        ...
    </igx-banner>

// banner.component.ts
...
export class MyBannerComponent {
    ...
    public handleOpen(event) {
        event.cancel = true;
    }
}
Note

If the changes above are applied, the banner will never open, as the opening event is always cancelled.

Styling

Using the Ignite UI for Angular Theming, we can alter the igx-banner appearance. We are going to build upon the animations sample and modify the igx-banner component to have more distinguished messages. Since igx-banner includes igx-button, you can directly refer to the igx-button styling guide for details, specific to styling the buttons themselves.

Import theme

First, in order for us to use the functions exposed by the theme engine, we need to import the index file in our style file: 

// in styles.scss
@import '~igniteui-angular/lib/core/styles/themes/index';

Define palette & colors

After we've imported the index file we can go ahead and use the igx-color function to define some color variables we would like to use in our custom theme. We are going to use these for our custom igx-banner styling in conjunction with our own color palette where we can specify our two main colors to be used by the component as well as the message color. Fist define a custom palette and pass our main colors:

// in styles.scss
$my-primary-color:#fde71d;
$my-secondary-color: #C0C0C0;
$my-info-color: #ff0000;

$my-color-palette: igx-palette(
    $primary: $my-primary-color,
    $secondary: $my-secondary-color,
    $info: $my-info-color
);

In order to see our custom palette and colors applied, we need to pass these to a theme function. So in one bold move we will create a custom theme and pass our colors to a number of predefined igx-banner-theme parameters . Let's say we have decided modifying these specific parameters will be more than sufficient to make our component look the way we like. It is really convenient to take use of the previously created palette and base our new colors on the colors defined.

// in styles.scss
$custom-banner-theme: igx-banner-theme(
    $palette: $my-color-palette,
    $banner-message-color: igx-color($my-color-palette, "info"),
    $banner-illustration-color: igx-color($my-color-palette, "info"),
    $banner-background: igx-color($my-color-palette, "secondary", 200)
);

As igx-banner uses igx-button, we can go a bit further and style these as well. So we go outside the igx-banner topic and to complement the overall igx-banner theme styling we will create a custom button theme like: 

// in styles.scss
$my-button-primary-color:#fde71d;
$my-button-secondary-color: #09f;

$my-button-color-palette: igx-palette(
    $primary: $my-button-primary-color,
    $secondary: $my-button-secondary-color
);
$custom-button-theme: igx-button-theme(
    $palette: $my-button-color-palette
);

Applying

All that's left is to properly scope our newly created theme.

Globally

In case you want this newly created igx-banner theme to be applied globally in your app, all that is needed is to include the theme in your app root style file:

// in styles.scss
// Pass our banner theme to the `igx-banner` mixin
    @include igx-banner($custom-banner-theme);
// Pass our button theme to the `igx-button` mixin
    @include igx-button($custom-button-theme);

Scoped

There may be a case where you want a particular igx-banner be styled differently than the others in the app. This will require to use angular specific pseudo-class selectors like :host, ::ng-deep, etc. Additionally all of the above steps need to be moved from styles.scss to the component.scss file.

Note

If the component is using an Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep.

On the other side, in order to prevent our custom theme to leak to other components, be sure to include the :host selector before ::ng-deep:

// in component.scss
:host {
    ::ng-deep {
        // Pass our banner theme to the `igx-banner` mixin
        @include igx-banner($custom-banner-theme);
        // Pass our button theme to the `igx-button` mixin
        @include igx-button($custom-button-theme);
    }
}

Styling Demo

API Reference