Mastering Android Immersive Status Bar with ZanImmersionBar: A Complete Guide

Background and Evolution of Immersive Status Bar

Android introduced immersive UI gradually. Before API 19 only hide status and navigation bars. API 19 (Android 4.4) added FLAG_TRANSLUCENT_STATUS and FLAG_TRANSLUCENT_NAVIGATION and the ability to draw a view matching the status‑bar height. API 21 (Android 5.0) added android:statusBarColor, setStatusBarColor(), FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS and removed the translucent flag. API 23 (Android 6.0) added SYSTEM_UI_FLAG_LIGHT_STATUS_BAR for dark icons and later SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR for navigation‑bar icons.

Manufacturers such as MIUI and EMUI add custom flags, making cross‑device handling complex.

Implementation per API Level

API 19–20 (Android 4.4–4.4W)

Enable immersion by adding the translucent flags and inserting a placeholder view with height equal to the status bar.

getWindow().addFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_STATUS);
getWindow().addFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION);

Placeholder view (XML):

<View
    android:layout_width="match_parent"
    android:layout_height="@dimen/status_bar_height"
    android:background="@color/colorPrimary" />

API 21+ (Android 5.0 and later)

Draw system bars directly:

getWindow().addFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS);
getWindow().clearFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_STATUS);
getWindow().setStatusBarColor(getResources().getColor(R.color.holo_red_light));

For a transparent navigation bar also clear FLAG_TRANSLUCENT_NAVIGATION and call setNavigationBarColor().

API 23+ (Android 6.0)

Set dark icons on a light status bar:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    getWindow().getDecorView().setSystemUiVisibility(
        View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN |
        View.SYSTEM_UI_FLAG_LIGHT_STATUS_BAR);
}

Use SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR for navigation‑bar icons on Android 8.0+.

ZanImmersionBar Library

ZanImmersionBar wraps the above steps into a fluent API that automatically selects the correct flags for the current Android version, handles MIUI/EMUI customizations, and resolves common layout issues such as status‑bar overlap, notch screens, and soft‑keyboard conflicts.

Core Workflow

ZanImmersionBar.with(this).init();

The init() method:

Collects user‑defined BarParams (colors, alpha, dark‑font flags, etc.).

Calls setBar() to apply the appropriate flags for the device’s API level.

Handles notch screens, MIUI/EMUI flags, and navigation‑bar visibility.

Typical Usage in an Activity

public class BaseActivity extends AppCompatActivity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ZanImmersionBar.with(this).init();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        ZanImmersionBar.with(this).destroy(); // release listeners and map entries
    }
}

Fragment Integration

Initialize immersion after the host activity has called init():

public void initImmersionBar() {
    ZanImmersionBar.with(this)
        .statusBarDarkFont(true)
        .statusBarColor(R.color.btn1)
        .navigationBarColor(R.color.btn1)
        .init();
}

Dialog and PopupWindow Support

Dialog usage is identical to activity usage:

ZanImmersionBar.with(this).init();

For a PopupWindow that should extend behind the system bars, disable clipping:

popupWindow.setClippingEnabled(false);

Resolving Status‑Bar Overlap

When a layout does not reserve space for the status bar, ZanImmersionBar offers several strategies:

Custom placeholder view : Add a view with height @dimen/status_bar_height and let ZanImmersionBar treat it as the status‑bar background.

fitsSystemWindows : Set android:fitsSystemWindows="true" on the root layout (not recommended for fragments).

statusBarView(view) : Pass a view to ZanImmersionBar; it will automatically adjust the view’s height and background.

titleBar(view) or titleBarMarginTop(view) : ZanImmersionBar adds padding or margin equal to the status‑bar height for a custom toolbar.

Example using statusBarView:

ZanImmersionBar.with(this)
    .statusBarView(findViewById(R.id.fake_status_bar))
    .init();

Key Implementation Details of ZanImmersionBar

The library stores user parameters in a BarParams object (statusBarColor, navigationBarColor, alpha values, dark‑font flags, etc.). During init() it:

Updates the BarParams from the fluent calls.

Calls setBar() which:

Detects the Android version.

For API ≥ 21 calls initBarAboveLOLLIPOP() to set FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS, clear translucent flags, and apply colors with optional alpha blending.

For API < 21 calls initBarBelowLOLLIPOP() to add the translucent flag and insert a placeholder view.

Applies manufacturer‑specific flags (MIUI, EMUI) for dark status‑bar fonts.

Handles notch screens via fitsNotchScreen().

Adjusts layout overlap ( fitsLayoutOverlap()), soft‑keyboard conflicts ( fitsKeyboard()), and view transformations ( transformView()).

Provides destroy() to remove listeners and clear the internal map that tracks ZanImmersionBar instances per activity.

Best Practices

Initialize ZanImmersionBar in a base activity so all subclasses share a single configuration point.

Always call destroy() in onDestroy() to avoid memory leaks.

Specify a status‑bar color when using fitsSystemWindows or titleBar methods; otherwise the default transparent color may cause visual glitches.

For MIUI devices call setMIUIBarDark() to enable dark‑font flags.

Summary

Handling Android immersive status and navigation bars requires understanding three API stages, manufacturer customizations, and layout adjustments for notch screens. ZanImmersionBar abstracts these complexities into a chainable API that works across activities, fragments, dialogs, and popup windows while offering flexible solutions for status‑bar overlap.