DOCSEARCHbyAlgolia
Submit Docs

ImmersionBar Android Library

repository·master·Indexed 9 days ago

https://github.com/gyf-dev/immersionbar

An Android library (supporting API 19+) for implementing immersive edge-to-edge UIs. It provides a fluent API to manage status bars, navigation bars, and notch/cutout compatibility, including support for transparency, custom colors, and soft keyboard conflict resolution. Compatible with Activities, Fragments, Dialogs, and PopupWindows.

Tokens
8.2K
Snippets
28
Records
34
Agent score
90%

What's inside ImmersionBar

  1. Implement ImmersionBar in a Fragment

    master

    Depending on how your Fragment is managed, use one of the following approaches:

    1. ViewPager2: If using BEHAVIOR_RESUME_ONLY_CURRENT_FRAGMENT, call the ImmersionBar initialization directly in the Fragment's onResume() method.
    2. show()/hide() management: If controlling visibility via show() and hide(), implement the immersion logic in both onResume() and onHiddenChanged(boolean hidden) (where hidden is false).
    3. Fragmentation framework: If using the Fragmentation library, refer to the FragmentFiveActivity and BaseFiveFragment examples in the project demo.

  2. Recommended BaseActivity implementation

    master

    For best practices, implement ImmersionBar initialization and destruction in a BaseActivity. This ensures consistent behavior across all activities in your app.

    Key Lifecycle Steps:

    1. onCreate: Initialize with .init().
    2. onResume: (Optional) Re-initialize if supporting Huawei EMUI3 devices with orientation changes.
    3. onDestroy: Call .destroy() to prevent leaks.
    4. onConfigurationChanged: (Optional) Re-initialize if supporting Android 4.4 or Huawei EMUI3.1 with orientation changes.
    public class BaseActivity extends AppCompatActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ImmersionBar.with(this).init();  
    }
  
    @Override
    protected void onResume() {
        super.onResume();
        // Required for Huawei EMUI3 if orientation changes are enabled
        if (OSUtils.isEMUI3_x()) {
            ImmersionBar.with(this).init();   
        }
    }
  
    @Override
    protected void onDestroy() {
        super.onDestroy();
        ImmersionBar.with(this).destroy();
    }
  
    @Override
    protected void onConfigurationChanged(Configuration newConfig) {
        super.onConfigurationChanged(newConfig);
        // Required for Android 4.4 or Huawei EMUI3.1 if orientation changes are enabled
        ImmersionBar.with(this).init();   
    }
}

  3. Configure ProGuard rules for ImmersionBar

    master

    If you are using ImmersionBar version 3.1.1 or above, no ProGuard configuration is required.

    For versions below 3.0.0, add the following rules to your proguard-rules.pro file to prevent obfuscation issues:

    -keep class com.gyf.immersionbar.* {*;} 
-dontwarn com.gyf.immersionbar.**

  4. Implement ImmersionBar in a Dialog

    master

    ImmersionBar supports both DialogFragment and standard Dialog objects:

    • DialogFragment: Use ImmersionBar.with(this).init().
    • Standard Dialog: Since version 3.3.2, ImmersionBar automatically parses the Activity from the dialog. It also automatically destroys itself when the dialog is closed, so manual destroy() calls are unnecessary.

    Java Example (Standard Dialog):

    ImmersionBar.with(dialog).init();

    Kotlin Example (Standard Dialog):

    dialog.immersionBar()
    ImmersionBar.with(this).init();

  5. Set dark status bar font for white backgrounds

    master

    If you have a white status bar background but the device does not support changing the status bar font to dark, use .statusBarDarkFont(true, alpha).

    This works by: If the device supports dark fonts, it sets them to black. If the device does not support it, it applies the specified transparency (alpha) to the status bar instead.

    ImmersionBar.with(this)
    .statusBarDarkFont(true, 0.2f)
    .init();

  6. Solve status bar and layout overlap

    master

    Choose one of the following six solutions to handle the overlap between the status bar and your layout top:

    1. Custom Dimen (Not recommended): Define a fixed status_bar_height in values-v19/dimens.xml and use it as a View height in your layout. This is discouraged because status bar heights vary by device.
    2. System fitsSystemWindows: Set android:fitsSystemWindows="true" on your root layout. If using this, you must specify a status bar color in ImmersionBar and call .init() after the layout is set.
    3. ImmersionBar fitsSystemWindows(boolean): Use .fitsSystemWindows(true). This requires specifying a status bar color.
    4. ImmersionBar statusBarView(View): Add a View with 0dp height above your toolbar in XML, then pass it to .statusBarView(view).
    5. ImmersionBar titleBar(View): Sets paddingTop on the provided view. Note: If using a custom XML title bar, the root node cannot be RelativeLayout or ConstraintLayout (or their subclasses).
    6. ImmersionBar titleBarMarginTop(View): Sets marginTop on the provided view.
    // Option 3: fitsSystemWindows
ImmersionBar.with(this)
    .fitsSystemWindows(true)
    .statusBarColor(R.color.colorPrimary)
    .init();

// Option 4: statusBarView
ImmersionBar.with(this)
    .statusBarView(view)
    .init();

// Option 5: titleBar
ImmersionBar.with(this)
    .titleBar(view)
    .init();

// Option 6: titleBarMarginTop
ImmersionBar.with(this)
    .titleBarMarginTop(view)
    .statusBarColor(R.color.colorPrimary)
    .init();

  7. Install ImmersionBar via Gradle

    master

    To use ImmersionBar, add the appropriate dependencies to your build.gradle file. For versions 3.1.1 and above (available on MavenCentral), use the com.geyifeng.immersionbar group ID. For older 3.0.0 versions on JCenter, use com.gyf.immersionbar.

    Required dependencies:

    • immersionbar: The core library.
    • immersionbar-ktx (Optional): Kotlin extensions.
    • immersionbar-components (Optional/Deprecated): Quick implementation for Fragments.
    // For 3.1.1+ (MavenCentral)
implementation 'com.geyifeng.immersionbar:immersionbar:3.3.3'
implementation 'com.geyifeng.immersionbar:immersionbar-ktx:3.3.3'

// For 3.0.0 (JCenter)
implementation 'com.gyf.immersionbar:immersionbar:3.0.0'
implementation 'com.gyf.immersionbar:immersionbar-ktx:3.0.0'

  8. Solve EditText and Soft Keyboard Conflicts

    master

    To prevent the soft keyboard from overlapping with bottom input fields, use one of these two methods:

    1. ImmersionBar keyboardEnable: Enable keyboard support via the builder. You can also optionally specify WindowManager.LayoutParams to make the keyboard pop up automatically.
    2. System fitsSystemWindows: Set android:fitsSystemWindows="true" on the root node of your layout. This is only suitable for solid color status bars.
    ImmersionBar.with(this)
            .keyboardEnable(true)
            .init();

  10. Implement ImmersionBar in an Activity with ViewPager

    master

    When using ViewPager components within an Activity, you must listen to page changes to trigger immersion updates:

    • ViewPager2: Use registerOnPageChangeCallback to listen for changes.
    • ViewPager (Legacy): Use addOnPageChangeListener to listen for changes.
    • show()/hide() Fragments: If using manual show/hide for tabs, trigger ImmersionBar during tab switches.

  11. Implement immersion in a Fragment

    master

    There are two primary ways to implement immersion in a Fragment:

    1. Inheritance: Inherit from SimpleImmersionFragment or ImmersionFragment. Implement your immersion logic inside the initImmersionBar() method. Note that initImmersionBar() is only called if immersionBarEnabled() returns true (which is true by default).

    2. Interface Implementation: If you cannot inherit from the provided classes, implement the SimpleImmersionOwner interface (for SimpleImmersionFragment behavior) or the ImmersionOwner interface (for ImmersionFragment behavior).

    Comparison of Fragment Classes

    MethodSimpleImmersionFragmentImmersionFragment
    initImmersionBar() (Immersion logic)✅✅
    immersionBarEnabled() (Control execution)✅✅
    onLazyBeforeView() (Before view init)❌✅
    onLazyAfterView() (After view init)❌✅
    onVisible() (When visible)❌✅
    onInvisible() (When invisible)❌✅

  12. Implement immersion in a Dialog

    master

    To use ImmersionBar with Dialogs, use the following patterns:

    • DialogFragment: Use ImmersionBar.with(this).init();
    • Other Dialogs: Use ImmersionBar.with(this, dialog).init();

    CRITICAL: When using ImmersionBar with a Dialog, you must call the destroy() method when the dialog is destroyed to prevent memory leaks.

    // For DialogFragment
ImmersionBar.with(this).init();

// For other Dialogs
ImmersionBar.with(this, dialog).init();

// IMPORTANT: Call this when dialog is destroyed
ImmersionBar.destroy();