Statusbar

    Framework7 comes with statusbar component that may help to customize app statusbar and its behavior and solve the following problem:

    iOS 7+ allows you to have make full screen apps. But there could be such problem when statusbar overlap your app:

    Not good!

    Good!

    Framework7 helps you to solve this issue. It automatically detects if your app in full screen mode, and automatically adds with-statusbar class to <html> element if app is in full screen mode (or removes this class if app is not in full screen mode).

    With this with-statusbar class (when app in full screen mode) the app root element has additional padding on top to move a whole app's content on size of Statusbar.

    Statusbar Layout

    Now, when Framework7 did its job on this part, we can control Statusbar behavior, we need to add <div class="statusbar"> as a direct child of app root element:

    <body>
      <!-- App root element -->
      <div id="app">
        <!-- Statusbar overlay element -->
        <div class="statusbar"></div>
        ...
      </div>
    </body>

    This statusbar div is always fixed on top of screen and hidden by default. It becomes visible only when app is in full screen mode and html has with-statusbar class.

    Statusbar Styling

    If we need to change statusbar background color we may use simple CSS rule:

    .statusbar {
      background: pink;
    }

    Such logic allows pretty flexible control over Statusbar background and we can change its background dynamically.

    For example, we have dark left-side panel with cover effect. We may change Statusbar background to more dark color when panel opened:

    /* Default Statusbar background */
    .statusbar {
      background: pink;
      /* We can add transition for smooth color animation */
      transition: 400ms;
    }
    
    /* Change Statusbar background when panel opened */
    html.with-panel-left-cover .statusbar {
      background: #222;
    }
    • On home-screen web apps Statusbar text color is always white. There is no way to change it.

    • In cordova apps Statusbar text color is always black by default. It can be with cordova plugin cordova-plugin-statusbar and using its api or Framework7 Statusbar API

    Statusbar App Parameters

    It is possible to control some default statusbar behavior by passing statusbar related parameters on app init under statusbar property:

    var app = new Framework7({
      statusbar: {
        iosOverlaysWebView: true,
      },
    });

    Now let's look at list of all available parameters

    Parameter Type Default Description
    enabled boolean true Enables statusbar handling by Framework7. Disable it if you don't want Framework7 to handle statusbar behavior
    overlay string
    boolean
    auto Can be true, false, auto. Defines whether the statusbar overlay should be visible or not. In case of auto Framework7 will detect it automatically depending whether the app is in fullscreen mode or not
    iosBackgroundColor string Hex string (#RRGGBB) with background color when app running on iOS device. If passed then it will override CSS value
    androidBackgroundColor string Hex string (#RRGGBB) with background color when app running on Android device. If passed then it will override CSS value
    scrollTopOnClick boolean true If enabled, then click on statusbar overlay will scroll top page content to the top.

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    iosOverlaysWebView boolean true

    Makes the statusbar overlay or not overlay the WebView when app is running on iOS device.

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    androidOverlaysWebView boolean true

    Makes the statusbar overlay or not overlay the WebView when app is running on Android device.

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    iosTextColor string black

    Statusbar text color when app is running on iOS device. Can be white or black

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    androidTextColor string black

    Statusbar text color when app is running on Android device. Can be white or black

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    Statusbar App Methods

    After app initialization we can control statusbar by using statusbar related app methods:

    app.statusbar.hide() Hide statusbar. In webapp it just hides statusbar overlay, but in cordova app it will hide statusbar at all.

    Hiding device statusbar is available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    app.statusbar.show() Show statusbar
    app.statusbar.overlaysWebView(overlays) Makes the statusbar overlay or not overlay the WebView
    • overlays - boolean - does it overlay or not

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    app.statusbar.setTextColor(color) Set/change statusbar text color.
    • color - string - text color, can be white or black

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar

    app.statusbar.setBackgroundColor(hex) Set/change statusbar background color
    • hex - string - Hex string (#RRGGBB) with background color
    app.statusbar.isVisible() Returns true if system statusbar is visible and false when it is not visible

    This functionality is only available when app is running under cordova/phonegap environment with installed cordova-plugin-statusbar