Banners

Announcements that appear across every screen in your app

Banners are a powerful way to push critical information to your users.

Tapping a banner can trigger other actions, like showing a modal with more information, opening a web-link to an announcement, or showing an alert.

Banners are only supported in iOS 13 or newer. If your app supports iOS 12, a banner action won't have any effect. You can use a Conditional Action checking OS version to show an alternative message format on iOS 12 (Alert or Modal) if needed.

Examples

A bottom banner, top banner with cycle-message button, and a themed bottom banner

Banner Action Config

Banners have actionType banner and an actionData object with the following keys:

• body [string, required]: the string to show in the banner

• showDismissButton [bool, optional]: if true, a close button ("X") is shown, allowing the user to dismiss this banner. If false, the banner can not be dismissed. Defaults to true if omitted.

• maxLineCount [int, optional]: if set, limits the number of lines. If omitted, defaults to 4 lines. If the max line count is reached, the string will be truncated with an ellipsis ("..."). If set to 0, the line count isn't limited (although the banner is limited to 20% of screen height).

• tapActionName [string, optional]: the name of an action to trigger if the user taps the banner message. No action is fired if omitted.

• themeName [string, optional]: if provided this banner will use the specified theme (overriding the default theme). See themeing information below.

• preferredPosition [string, optional]: one of "top" or "bottom". For a given app, it's best to not mix positions. If both are used the banner area will use the position of the last banner presented.

Design Considerations

Banners show a message across every screen of your app, and should be used sparingly for important announcements.

Only convey the most critical information in the banner text itself, keeping it as short as possible. Provide more detailed information if they tap the banner with a modal, alert or web-link in embedded browser launched via tapActionName. If you have a tap action, consider ending your body string with "Tap for details.", or a similar hint.

Banners should almost always be user dismissable, allowing users to reclaim the screen space. Exceptions to this rule should be exceedingly rare (example: company is shutting down and users need to export data).

If you present multuple banners at the same time, the user will see a "<>" button on the left of the banner to cycle through the messages. You can try this in our Sample App.

Be sure to test banners in your app before deploying them. Our banner area is injected into the main window of your app, and shifts your app's content using additionalSafeAreaInsets on the root view controller. This typically works well, and Apple controllers like UITabBarController or UINavigationController handle this automatically. If you have your own root view controller which has hardcoded insets or ignores layout guides, the banners may cover important parts of your app UI. To fix issues, make sure your root view controller respects safe insets / layout guides.

Theming Banners

Banners respect your default theme, or you can a theme for a specific banner with the themeName property.

There are 2 specific properties in themes for banners:

• bannerBackgroundColor: the banner background color

• bannerForegroundColor: the foreground color for text and buttons

By default, banners are yellow with black text, in the system font.

Banners will respect shared theme properties, like the fontName. See the full themes documentation for details.

Example Config

The config below from the Sample App, and generated the banners in the screenshots above.

"short_banner": {
    "actionType": "banner",
    "actionData": {
        "body": "A short banner!",
        "tapActionName": "nested_alert"
    }
},
"long_banner": {
    "actionType": "banner",
    "actionData": {
        "body": "Welcome to critical moments! App wide banners can give your users crucial information.",
        "tapActionName": "nested_alert"
    }
},
"very_long_banner": {
    "actionType": "banner",
    "actionData": {
        "body": "Welcome to critical moments! App wide banners can give your users crucial information. This one happens to be really really long, and will probably be truncated eventually. It was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness, it was the epoch of belief, it was the epoch of incredulity, it was the season of light, it was the season of darkness, it was the spring of hope, it was the winter of despair",
        "tapActionName": "nested_alert"
    }
},
"custom_theme_banner": {
    "actionType": "banner",
    "actionData": {
        "body": "This banner has a custom theme+action set in config. Tap me!",
        "themeName": "blackAndWhiteTheme",
        "tapActionName": "nested_alert"
    }
},
"top_banner": {
    "actionType": "banner",
    "actionData": {
        "body": "This banner will appear at the top! Any banner can specify top or bottom position.",
        "preferredPosition": "top",
        "tapActionName": "nested_alert"
    }
},
"undismissable_banner": {
    "actionType": "banner",
    "actionData": {
        "body": "You are stuck with me... unless you use the \"Clear all banners\" action",
        "showDismissButton": false,
        "tapActionName": "nested_alert"
    }
},
"single_line_banner": {
    "actionType": "banner",
    "actionData": {
        "body": "This message will truncate after the first line, unlike the default of 4 lines.",
        "maxLineCount": 1,
        "tapActionName": "nested_alert"
    }
}