Banners
Announcements that appear across every screen in your app
Last updated
Announcements that appear across every screen in your app
Last updated
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.
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.
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.
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.
The config below from the Sample App, and generated the banners in the screenshots above.
