Skip to content
Capgo

Getting Started

  1. Install the package

    Terminal window
    npm i @capgo/home-indicator

  2. Sync with native projects

    Terminal window
    npx cap sync

  3. Configure the plugin

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

  4. Auto-hide configuration

    import { HomeIndicator } from '@capgo/home-indicator';
    

    // Configure auto-hide behavior
    await HomeIndicator.setAutoHidden({
      autoHidden: true // Enable auto-hide
    });
    

    // The home indicator will automatically hide after a few seconds
    // and reappear when the user touches the screen

  5. Advanced usage

    import { HomeIndicator } from '@capgo/home-indicator';
    import { App } from '@capacitor/app';
    

    export class ImmersiveMode {
      private isImmersive = false;
    

      async enterImmersiveMode() {
        this.isImmersive = true;
    

        // Hide home indicator
        await HomeIndicator.hide();
    

        // Enable auto-hide for better UX
        await HomeIndicator.setAutoHidden({ autoHidden: true });
    

        // Hide status bar for full immersion
        // StatusBar.hide(); // If using @capacitor/status-bar
      }
    

      async exitImmersiveMode() {
        this.isImmersive = false;
    

        // Show home indicator
        await HomeIndicator.show();
    

        // Disable auto-hide
        await HomeIndicator.setAutoHidden({ autoHidden: false });
    

        // 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 }>

setAutoHidden(options: { autoHidden: boolean })

Configure auto-hide behavior for the home indicator.

Parameters:

  • options.autoHidden: boolean - Enable or disable auto-hide

Returns: Promise<void>

Interfaces

interface AutoHiddenOptions {
  autoHidden: boolean;
}


interface HiddenResult {
  hidden: boolean;
}

Platform Notes

iOS

  • Only works on devices with home indicator (iPhone X and later)
  • Requires iOS 11.0 or later
  • Auto-hide makes the indicator translucent and hides after inactivity
  • 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. Auto-Hide for Games: Use auto-hide for better gaming experience

    // For games, auto-hide provides the best balance
    await HomeIndicator.setAutoHidden({ autoHidden: true });

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

  4. 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

Auto-hide not working:

  • Auto-hide requires user interaction to activate
  • The indicator becomes translucent, not completely hidden

Indicator reappears unexpectedly:

  • This is normal iOS behavior for system gestures
  • Use auto-hide for less intrusive behavior