Angular Banner Component Overview
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.
Angular Banner Example
Getting Started with Ignite UI for Angular Banner
To get started with the Ignite UI for Angular Banner component, first you need to install Ignite UI for Angular. In an existing Angular application, type 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 your app.module.ts file.
// app.module.ts
...
import { IgxBannerModule } from 'igniteui-angular';
// import { IgxBannerModule } from '@infragistics/igniteui-angular'; for licensed package
@NgModule({
...
imports: [..., IgxBannerModule],
...
})
export class AppModule {}
Alternatively, as of 16.0.0
you can import the IgxBannerComponent
as a standalone dependency, or use the IGX_BANNER_DIRECTIVES
token to import the component and all of its supporting components and directives.
// home.component.ts
...
import { IGX_BANNER_DIRECTIVES } from 'igniteui-angular';
// import { IGX_BANNER_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package
@Component({
selector: 'app-home',
template: `
<igx-banner>
You are currently offline.
</igx-banner>
`,
styleUrls: ['home.component.scss'],
standalone: true,
imports: [IGX_BANNER_DIRECTIVES]
/* or imports: [IgxBannerComponent] */
})
export class HomeComponent {}
Now that you have the Ignite UI for Angular Banner module or directives imported, you can start with a basic configuration of the igx-banner
component.
Using the Angular Banner Component
Show Banner
In order to display the banner component, use its open()
method and call it on a button click. The banner appears relative to where the element was inserted in the page template, moving all other content. It typically shows some non-intrusive content that requires minimal user interaction to be dismissed.
<!--banner.component.html-->
<igx-icon (click)="connectionBanner.open()">refresh</igx-icon>
...
<igx-banner #connectionBanner>
You are currently offline.
</igx-banner>
Note
The IgxBannerModule
includes a default banner button Dismiss
, which closes the banner.
Examples
The IgxBannerComponent
allows templating of its content while still sticking as closely as possible to the material design banner guidelines.
Changing the banner message
Configuring the message displayed in the banner is easy - just change the content you are passing to the igx-banner
tag. The text will show up in the specified banner area and the banner will use its default template when displaying it. Below, we will change the content of our sample banner to be a bit more descriptive:
<!--banner.component.html-->
<igx-banner #connectionBanner>
You have lost connection to the internet. This app is offline.
</igx-banner>
Adding an icon
An igx-icon
can be displayed in the banner by passing it to the banner's content. The icon 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 to position all of them at the beginning. It is strongly advised to pass only one igx-icon
directly to the banner.
To pass an igx-icon
to you banner, simply insert it in the banner's 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>
If you want to use an igx-icon
in your banner message, wrap it in a span
tag:
<!--banner.component.html-->
<igx-banner #connectionBanner>
You have lost connection to the internet. This app is offline.
<span>
<igx-icon>signal_wifi_off</igx-icon>
</span>
</igx-banner>
Changing the banner button
The IgxBannerModule
exposes a directive for templating the banner buttons - IgxBannerActionsDirective
. This directive allows you to override the default banner button (Dismiss
) and add user-defined custom actions.
<!--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.toggle()">Toggle Banner</button>
</igx-banner-actions>
</igx-banner>
Applying custom animations
The banner component comes with the animationSettings
property that allows applying custom opening and closing animations. Developers can choose between self-defined animations, and those from our Animation suite
. The default ones, used by the banner, are growVerIn
for entering and growVerOut
for exiting.
Let's change the animations that our banner uses, so that it slides in and out:
<!--banner.component.html-->
<igx-banner #connectionBanner [animationSettings]="animationSettings">
...
</igx-banner>
// banner.component.ts
import { IgxBannerComponent, slideInLeft, slideOutRight } from 'igniteui-angular'
// import { IgxBannerComponent, slideInLeft, slideOutRight } from '@infragistics/igniteui-angular'; for licensed package
...
export class MyBannerComponent {
...
public animationSettings = {
openAnimation: slideInLeft,
closeAnimation: slideOutRight
}
...
}
Binding to events
The banner component emits events when changing its state - opening
and opened
are called when the banner is shown (before and after, resp.), while closing
and closed
are emitted when the banner is closed. The ing events (opening
, closing
) 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 opening
, 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 (opening)="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.
Advanced Example
Let's create a banner with two custom buttons - one for dismissing the notification and one for turning on the connection. We can pass custom action handlers using the igx-banner-actions
selector:
<!--banner.component.html-->
<igx-banner class="offline-banner" #connectionBanner [animationSettings]="animationSettings">
<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>
Note
According to Google's Material Design
guidelines, a banner should have a maximum of 2 buttons present. The IgxBannerComponent
does not explicitly limit the number of elements under the igx-banner-actions
tag, but it is strongly recommended to use up to 2 if you want to adhere to the material design guidelines.
The dismiss option ('Continue Offline'
) doesn't need any further logic, so it can just call the close()
method. The confirm action ('Turn On Wifi'
), however, requires some additional logic, so we have to define it in the component. Then, we will create onNetworkStateChange
Observable and subscribe to it. The last step is to call the refreshBanner()
method on each change, which will toggle the banner depending on the wifiState
.
The banner will also have a WiFi icon in the navbar. As the subscription fires on any change of the wifiState
, the icon will not only toggle the banner, but change according to the state of the connection:
<!--banner.component.html-->
<igx-navbar title="Gallery">
<igx-icon (click)="wifiState = !wifiState">
{{ wifiState ? 'signal_wifi_4_bar' : 'signal_wifi_off' }}
</igx-icon>
</igx-navbar>
Finally, we will add a toast
, displaying a message about the WiFi state. The results of the templated banner can be seen in the demo below:
Styling
First, in order to use the functions exposed by the theme engine, we need to import the index file in our style file:
@use "igniteui-angular/theming" as *;
// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';
Following the simplest approach, we create a new theme that extends the banner-theme
and accepts the $banner-message-color
, $banner-background
and the $banner-illustration-color
parameters.
$custom-banner-theme: banner-theme(
$banner-message-color: #151515,
$banner-background: #dedede,
$banner-illustration-color: #666666
);
Using CSS variables
The last step is to pass the custom banner theme:
@include css-vars($custom-banner-theme);
Using mixins
In order to style components for older browsers, like Internet Explorer 11, we have to use a different approach, since it doesn't support CSS variables.
If the component is using the Emulated
ViewEncapsulation, it is necessary to penetrate
this encapsulation using ::ng-deep
. To prevent the custom theme to leak into other components, be sure to include the :host
selector before ::ng-deep
:
:host {
::ng-deep {
// Pass the custom banner theme to the `igx-banner` mixin
@include banner($custom-banner-theme);
}
}
Using color palettes
Instead of hardcoding the color values, like we just did, we can achieve greater flexibility in terms of colors by using the igx-palette
and igx-color
functions.
The igx-palette
function generates a color palette based on the primary and secondary colors that are passed:
$white-color: #dedede;
$black-color: #151515;
$light-banner-palette: palette($primary: $white-color, $secondary: $black-color);
And then with igx-color
we can easily retrieve color from the palette.
$custom-banner-theme: banner-theme(
$banner-message-color: color($light-banner-palette, "secondary", 400),
$banner-background: color($light-banner-palette, "primary", 400),
$banner-illustration-color: color($light-banner-palette, "secondary", 100)
);
Note
The igx-color
and igx-palette
are powerful functions for generating and retrieving colors. Please refer to the Palettes
topic for detailed guidance on how to use them.
Using schemas
You can build a robust and flexible structure that benefits from schemas
.
Extend one of the two predefined schemas, that are provided for every component, in this case - light-banner
schema:
// Extending the banner schema
$light-toast-schema: extend($_light-toast,
(
banner-message-color: (
color: ("secondary", 400)
),
banner-background: (
color: ("primary", 400)
),
banner-illustration-color: (
color: ("secondary", 100)
)
)
);
// Defining banner with the global light schema
$custom-banner-theme: banner-theme(
$palette: $light-banner-palette,
$schema: $light-toast-schema
);
Don't forget to include the themes in the same way as it was demonstrated above.
API Reference
Additional components and/or directives with relative APIs that were used:
Theming Dependencies
Additional Resources
Our community is active and always welcoming to new ideas.