Tauri Plugin status-bar

🚧 WIP: This plugin is still in development and is currently unavailable.

A plugin for tauri@v2 to manage status bar.

Platform Supported

Platform	Supported
Linux	❌
Windows	❌
macOS	❌
Android	✅
iOS	✅

Setup

Install the status-bar plugin to get started.

1. Run the following command in the src-tauri folder to add the plugin to the project’s dependencies in Cargo.toml:

   cargo add tauri-plugin-status-bar@0.1 --target 'cfg(any(target_os = "android", target_os = "ios"))'

2. Modify lib.rs to initialize the plugin:

    #[cfg_attr(mobile, tauri::mobile_entry_point)]
    pub fn run() {
        tauri::Builder::default()
            .setup(|app| {
   +            #[cfg(mobile)]
   +            app.handle().plugin(tauri_plugin_status_bar::init())?;
                Ok(())
            })
            .run(tauri::generate_context!())
            .expect("error while running tauri application");
    }

3. Modify src-tauri/capabilities/mobile.json to Allow the frontend to execute some commands.

    {
      "$schema": "../gen/schemas/mobile-schema.json",
      "identifier": "mobile",
      "description": "Capability for the main window on mobile platform",
      "windows": ["main"],
      "permissions": [
   +    "status-bar:default"
      ],
      "platforms": ["android", "iOS"]
    }

   All permissions list.

4. Install the JavaScript Guest bindings using your preferred JavaScript package manager:

   pnpm add tauri-plugin-status-bar-api@0.1

Config

Due to the Tauri plugin being unable to execute operations before the webview loads, it is not possible to initialize user-defined configurations within the plugin.

1. Make the statusbar overlay the WebView at startup.

   • Android For the initialization configuration, you can modify the file src-tauri/gen/android/app/src/main/res/values/themes.xml and add the following configuration in the default theme Theme.tauri_app.

     The file for modifying the dark theme is src-tauri/gen/android/app/src/main/res/values-night/themes.xml.

     <item name="android:windowTranslucentStatus">true</item>

     • true: the status bar overlays the WebView.
     • false: the status bar not overlays the WebView.

   • iOS Starting with iOS 11 you must include viewport-fit=cover in your viewport meta tag of index.html if you want the status bar to overlay the webview:

     <meta name="viewport" content="initial-scale=1, width=device-width, viewport-fit=cover" />

   If the status bar overlays the webview, you also need to configure the background color to be transparent, and then set the text foreground color to dark or light based on the color of the webview.

2. Set the background color of the statusbar at startup.

   • Android

     <item name="android:statusBarColor">@android:color/black</item>

     There are some available formats that can be set, such as:

     • Reference the color resources defined in the res/values/colors.xml file: @color/purple_500
     • Directly use ARGB or RGB format hexadecimal color values: #FF0000FF, #800000FF, #0000FF
     • Reference the color attributes in the theme: ?attr/colorPrimaryDark
     • Reference the colorStateList file defined in the res/color/ folder: @color/custom_color_state
     • Use the transparent value provided by the system: @android:color/transparent
     • Reference system-defined color resources: @android:color/holo_blue_dark

   • iOS

     Since Tauri does not expose AppDelegate, the iOS platform cannot configure this option during app initialization.

3. Set the status bar style at startup.

   • Android

     <item name="android:windowLightStatusBar">true</item>

     • true: the status bar text is dark.
     • false: the status bar text is light.

   • iOS

     <key>UIStatusBarStyle</key>
     <!-- default -->
     <string></string>
     <!-- light content -->
     <string>UIStatusBarStyleLightContent</string>
     <!-- dark content -->
     <string>UIStatusBarStyleDarkContent</string>

     Add these configurations in file src-tauri/Info.ios.plist.

4. Hide the status bar at startup.

   • Android

     <item name="android:windowTranslucentNavigation">true</item>
     <item name="android:windowLayoutInDisplayCutoutMode">shortEges</item>
     <item name="android:windowFullscreen">true</item>

     windowLayoutInDisplayCutoutMode Added in API level 27. If your App's minimum supported version is lower than Android@8.1, you need to move this configuration to the file src-tauri/gen/android/app/src/main/res/values-v27/themes.xml and src-tauri/gen/android/app/src/main/res/values-night-v27/themes.xml.

   • iOS

     <key>UIStatusBarHidden</key>
     <true/>
     <key>UIViewControllerBasedStatusBarAppearance</key>
     <false/>

     Add these configurations in file src-tauri/Info.ios.plist.

5. Use default scroll-to-top behavior.

   TODO

   On iOS, allows the WebView to use default scroll-to-top behavior. Defaults to false so you can listen to the "statusTap" event (described below) and customize the behavior instead.

Usage

setStatusBar

Set and change the status bar.

Support: iOS, Android

setStatusBar({
  overlay: true,
  backgroundColor: "transparent",
  lightStyle: false,
})
  .then(() => {
    console.log("setStatusBar successfully.");
  })
  .catch((err) => {
    console.error(`setStatusBar error: ${err}`);
  });

Parameter description:

• overlay: Make the statusbar overlay or not overlay the WebView.

• backgroundColor: Sets the background color of the statusbar by a hex string.

  There are some restrictions on color formats, for example, the following formats are correct:

  • 'transparent'
  • '000'
  • '#f34'
  • '#f3d74b'
  • '#3ff3d74b' (AARRGGBB)

• lightStyle： Use the lightContent statusbar (light text, for dark backgrounds).

  Note: In Android, only support version >=6. In higher versions, the foreground color will automatically adapt to light or dark based on the background color, which is also ineffective.

hide

Hide the statusbar.

Support: iOS, Android

hide()
  .then(() => {
    console.log("hide OK");
  })
  .catch((err) => {
    console.error(`hide error: ${err}`);
  });

In Android >=11, the hidden status bar can be temporarily displayed by swiping with a gesture.

isVisible

Read this property to see if the statusbar is visible or not.

Support: iOS, Android

isVisible()
  .then((visible) => {
    console.log(`isVisible OK: ${visible}`);
  })
  .catch((err) => {
    console.error(`isVisible error: ${err}`);
  });

onStatusTap

Listen for this event to know if the statusbar was tapped.

Only support a single callback, so repeated calls will cause the previous listener to be overridden.

If the parameter is empty, the listener will be canceled, and the default system status bar tap behavior will be used (i.e., double-tap to scroll to the top).

Support: iOS

onStatusTap(() => {
  // scroll-up with document.body.scrollTop = 0; or do whatever you want
});

// cancel the listener and use default system status bar tap behavior
onStatusTap();

Permission description