React Banner Overview

    The Ignite UI for React 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. It can also indicate actions to take based on the context of the message.

    Ignite UI for React Banner Example

    Usage

    First, you need to the install the corresponding Ignite UI for React npm package by running the following command:

    npm install igniteui-react

    You will then need to import the IgrBanner, its necessary CSS, and register its module, like so:

    import { IgrBannerModule, IgrBanner } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

IgrBannerModule.register();

    For a complete introduction to the Ignite UI for React, read the Getting Started topic.

    Show Banner

    In order to display the banner component, use its show 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.

    <IgrButton clicked={() => bannerRef.current.show()}>
    <span>Show Banner</span>
</IgrButton>

<IgrBanner ref={bannerRef}>
    <span key="message">You are currently offline.</span>
</IgrBanner>

    [!NOTE] The IgrBanner includes a default action button OK, which closes the banner.

    Examples

    The IgrBanner component 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 IgrBanner 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:

    <IgrBanner ref={bannerRef}>
    <span key="message">You have lost connection to the internet. This app is offline.</span>
</IgrBanner>

    Adding an icon

    An IgrIcon can be displayed in the banner by using the banner's prefix slot. The icon will always be positioned at the beginning of the banner message.

    [!NOTE] If several IgrIcon elements are inserted, the banner will try to position all of them at the beginning. It is strongly advised to pass only one IgrIcon directly to the banner.

    To pass an IgrIcon to your banner, use the prefix slot:

    <IgrBanner ref={bannerRef}>
    <IgrIcon key="icon" slot="prefix" name="signal_wifi_off"></IgrIcon>
    <span key="message">You have lost connection to the internet. This app is offline.</span>
</IgrBanner>

    If you want to use an IgrIcon in your banner message, simply insert it in the banner's content:

    <IgrBanner ref={bannerRef}>
    <span key="message">You have lost connection to the internet. This app is offline.</span>
    <IgrIcon key="icon" name="signal_wifi_off"></IgrIcon>
</IgrBanner>

    Changing the banner button

    The IgrBanner exposes the actions slot for templating the banner buttons. This allows you to override the default banner button (OK) and add user-defined custom actions.

    <IgrBanner ref={bannerRef}>
    <IgrIcon key="icon" slot="prefix" name="signal_wifi_off"></IgrIcon>
    <span key="message">You have lost connection to the internet. This app is offline.</span>
    <div key="actions" slot="actions">
        <IgrButton key="button" variant="flat" clicked={() => bannerRef.current.toggle()}>
            <IgrRipple key="ripple" />
            <span key="action-text">Toggle Banner</span>
        </IgrButton>
    </div>
</IgrBanner>

    Binding to events

    The banner component emits the igcClosing and igcClosed events when being closed. The igcClosing event is cancelable - it uses the CustomEvent interface and the emitted object has its cancelable property set to true. If we cancel the igcClosing event, the corresponding end action and event will not be triggered - the banner will not be closed and the igcClosed event will not be emitted.

    To cancel the closing event, call the preventDefault method.

    <IgrBanner ref={bannerRef}>
    ...
</IgrBanner>

const bannerRef = useRef<IgrBanner>(null);

useEffect(() => {
    bannerRef.current.nativeElement.addEventListener('igcClosing', (event) => {
        event.preventDefault();
    });
}, [])

    [!NOTE] If the changes above are applied, the banner will never close, as the closing 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 actions slot:

    <IgrBanner ref={bannerRef}>
    <IgrIcon key="icon" slot="prefix" name="signal_wifi_off"></IgrIcon>
    <span key="message">You have lost connection to the internet. This app is offline.</span>
    <div key="actions" slot="actions">
        <IgrButton key="button-offline" variant="flat" clicked={() => bannerRef.current.hide()}>
            <IgrRipple key="ripple-offline" />
            <span key="action-offline">Continue Offline</span>
        </IgrButton>
        <IgrButton key="button-wifi" variant="flat" clicked={() => refreshBanner()}>
            <IgrRipple key="ripple-wifi" />
            <span key="action-wifi">Turn On Wifi</span>
        </IgrButton>
    </div>
</IgrBanner>

    According to Google's Material Design guidelines, a banner should have a maximum of 2 buttons present. The IgrBanner does not explicitly limit the number of elements under the actions slot, 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 hide method. The confirm action (Turn On Wifi), however, requires some additional logic, so we have to define it in the component. Then, we will add an event listener for the click event. The last step is to call the refreshBanner() method on each change, which will toggle the banner depending on the wifiState.

    The navbar will have a Wifi icon and we will add an event listener for its click event as well. As the refreshBanner() method is called on each change, the icon will not only toggle the banner, but change according to the state of the connection:

    <IgrNavbar>
    <h1 key="header">Gallery</h1>
    <IgrIcon ref={iconRef} key="icon" name="signal_wifi_off" slot="end" onClick={() => refreshBanner()}></IgrIcon>
</IgrNavbar>

<IgrBanner ref={bannerRef}>
    ...
    <div key="actions" slot="actions">
        ...
        <IgrButton key="button-wifi" variant="flat" clicked={() => refreshBanner()}>
            <IgrRipple key="ripple-wifi" />
            <span key="action-wifi">Turn On Wifi</span>
        </IgrButton>
    </div>
</IgrBanner>

const bannerRef = useRef<IgrBanner>(null);
const iconRef = useRef<IgrIcon>(null);

const [wifiState, setWifiState] = useState(false);

function refreshBanner() {
    if (!wifiState) {
        iconRef.current.name = 'signal_wifi_4_bar';
        bannerRef.current.hide();
    } else {
        iconRef.current.name = 'signal_wifi_off';
        bannerRef.current.show();
    }
    setWifiState(current => !current);
}

    Finally, we will add a IgrToast, displaying a message about the WiFi state. The results of the templated banner can be seen in the demo below:

    Styling

    The IgrBanner component exposes several CSS parts which give you full control over its style:

    Name Description
    base The base wrapper of the banner component.
    spacer The inner wrapper that sets the space around the banner.
    message The part that holds the text and the illustration.
    illustration The part that holds the banner icon/illustration.
    content The part that holds the banner text content.
    actions The part that holds the banner action buttons. 
    igc-banner::part(spacer) {
  background: var(--ig-surface-600);
}

igc-banner::part(illustration) {
  color: var(--ig-surface-600-contrast);
}

igc-banner::part(content) {
  color: var(--ig-gray-900);
}

    API References

    Additional Resources