Getting Started

1. Install the package

   npm

   npm i @capgo/capacitor-home-indicator

   pnpm

   pnpm add @capgo/capacitor-home-indicator

   yarn

   yarn add @capgo/capacitor-home-indicator

   bun

   bun add @capgo/capacitor-home-indicator

2. Sync with native projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configure the plugin

   Hide Home Indicator:

   import { HomeIndicator } from '@capgo/capacitor-home-indicator';
   
   // Hide the home indicator
   await HomeIndicator.hide();

   Show Home Indicator:

   // Show the home indicator
   await HomeIndicator.show();
   
   // Check visibility status
   const { hidden } = await HomeIndicator.isHidden();
   console.log('Is hidden:', hidden);

   iOS

   No additional setup required. The plugin only works on iOS devices with a home indicator (iPhone X and later).

   Android

   This plugin has no effect on Android devices as they don’t have an iOS-style home indicator.

4. Advanced usage

   import { HomeIndicator } from '@capgo/capacitor-home-indicator';
   import { App } from '@capacitor/app';
   
   export class ImmersiveMode {
      private isImmersive = false;
   
      async enterImmersiveMode() {
        this.isImmersive = true;
   
        // Hide home indicator
        await HomeIndicator.hide();
   
        // Hide status bar for full immersion
        // StatusBar.hide(); // If using @capacitor/status-bar
      }
   
      async exitImmersiveMode() {
        this.isImmersive = false;
   
        // Show home indicator
        await HomeIndicator.show();
   
        // Show status bar
        // StatusBar.show(); // If using @capacitor/status-bar
      }
   
      async toggleImmersiveMode() {
        const { hidden } = await HomeIndicator.isHidden();
   
        if (hidden) {
          await this.exitImmersiveMode();
        } else {
          await this.enterImmersiveMode();
        }
      }
   
      setupAppLifecycle() {
        // Handle app state changes
        App.addListener('appStateChange', async ({ isActive }) => {
          if (!isActive && this.isImmersive) {
            // App went to background, might want to show indicator
            await HomeIndicator.show();
          } else if (isActive && this.isImmersive) {
            // App came to foreground, restore immersive mode
            await HomeIndicator.hide();
          }
        });
      }
    }

API Reference

Methods

hide()

Hide the home indicator.

Returns: Promise<void>

show()

Show the home indicator.

Returns: Promise<void>

isHidden()

Check if the home indicator is currently hidden.

Returns: Promise<{ hidden: boolean }>

Interfaces

interface HiddenResult {
  hidden: boolean;
}

Platform Notes

iOS

• Only works on devices with home indicator (iPhone X and later)
• Requires iOS 11.0 or later
• The indicator reappears when users swipe from the bottom

Android

• This plugin has no effect on Android
• Android uses different navigation gestures/buttons

Common Use Cases

1. Games: Full-screen gaming without distractions
2. Video Players: Immersive video playback
3. Photo Viewers: Full-screen photo galleries
4. Presentations: Distraction-free presentations
5. Kiosk Apps: Public display applications

Best Practices

1. User Control: Always provide a way to exit immersive mode

   // Add a gesture or button to toggle immersive mode
   const toggleButton = document.getElementById('toggle-immersive');
   toggleButton.addEventListener('click', () => {
     immersiveMode.toggleImmersiveMode();
   });

2. Respect System Gestures: Don’t interfere with system navigation

3. Save State: Remember user’s preference for immersive mode

Troubleshooting

Home indicator not hiding:

• Verify the device has a home indicator (iPhone X+)
• Check iOS version is 11.0 or higher
• Ensure the app has focus

Indicator reappears unexpectedly:

• This is normal iOS behavior for system gestures