Capacitor Home Indicator Plugin

Capacitor plugin to hide and show the iOS home indicator.

Features

• 🫥 Hide & show: Hide and show the home indicator at runtime.
• 🔍 State: Read the current plugin-managed state.
• 🧩 Zero-config: No changes to your native project required.
• 🤝 Compatibility: Need to control the Android navigation bar? Use the Navigation Bar plugin.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Home Indicator plugin is typically used to reduce visual distraction in fullscreen experiences on iOS, for example:

• Video players: Hide the home indicator while a video is playing so it fades out when the screen is idle.
• Games: Keep the focus on the gameplay by letting the home indicator auto-hide.
• Reading modes: Provide a distraction-free reading experience for articles, books, or documents.
• Kiosk-style apps: Minimize on-screen system UI for apps running in a presentation or kiosk context.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | >=8.x.x | Active support |

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-home-indicator` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-home-indicator
npx cap sync

This plugin is only available on iOS. On Android and Web, all methods reject as unimplemented. To control the navigation bar on Android, use the Navigation Bar plugin instead.

iOS

No additional setup is required. The plugin injects the home indicator override into the Capacitor bridge view controller automatically, so you do not need to subclass CAPBridgeViewController or edit your AppDelegate.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to hide and show the home indicator and check its current state.

Hide and show the home indicator

Hide and show the home indicator at runtime. Note that calling hide() sets the home indicator to auto-hide: it only fades out while the screen is idle and reappears as soon as the user touches the screen. Only available on iOS:

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

const hide = async () => {
  await HomeIndicator.hide();
};

const show = async () => {
  await HomeIndicator.show();
};

Check the current state

Check whether the home indicator is currently set to be hidden. This reflects the plugin-managed state, not the actual visibility on screen. Only available on iOS:

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

const isHidden = async () => {
  const { hidden } = await HomeIndicator.isHidden();
  return hidden;
};

API

• hide()
• isHidden()
• show()
• Interfaces

hide()

hide() => Promise<void>

Hide the home indicator.

The home indicator auto-hides while the screen is idle and reappears when the user touches the screen. The system does not allow permanently removing the home indicator.

Only available on iOS.

Since: 0.1.0

isHidden()

isHidden() => Promise<IsHiddenResult>

Check whether the home indicator is currently set to be hidden.

This reflects the plugin-managed state, not the actual visibility of the home indicator on screen (which the system controls). The state is kept in memory only and resets when the app is restarted.

Only available on iOS.

Returns: Promise<IsHiddenResult>

Since: 0.1.0

show()

show() => Promise<void>

Show the home indicator.

Only available on iOS.

Since: 0.1.0

Interfaces

IsHiddenResult

| Prop | Type | Description | Since | | ------------ | -------------------- | --------------------------------------------------------- | ----- | | hidden | boolean | Whether the home indicator is currently set to be hidden. | 0.1.0 |

Home Indicator Behavior

It is important to understand how the iOS home indicator behaves, as the operating system does not allow it to be permanently removed:

• Auto-hide only: Calling hide() sets the home indicator to auto-hide. The indicator only fades out while the screen is idle.
• Reappears on touch: As soon as the user touches the screen, the home indicator reappears. It fades out again once the screen becomes idle. This is a system behavior enforced by iOS and cannot be changed.
• In-memory state: The state managed by this plugin is kept in memory only. It resets to shown when the app is restarted, so call hide() again after your app relaunches if needed.

FAQ

How is this plugin different from other similar plugins?

It focuses on doing one thing well: hiding and showing the iOS home indicator at runtime with zero native setup, injecting the override into the Capacitor bridge view controller automatically so you never subclass CAPBridgeViewController or edit your AppDelegate. The API is fully typed, ships for both CocoaPods and Swift Package Manager, and is kept current with the latest Capacitor and iOS releases. If all you need is to toggle the home indicator, this is a focused, drop-in solution.

Why is the home indicator still visible after calling the hide method?

Calling hide() only sets the home indicator to auto-hide. The indicator fades out while the screen is idle and reappears as soon as the user touches the screen. This is a system behavior enforced by iOS and cannot be changed, since the operating system does not allow the home indicator to be permanently removed.

Does this plugin work on Android or the Web?

No, the plugin is only available on iOS. On Android and Web, all methods reject as unimplemented. If you want to control the navigation bar on Android, use the Navigation Bar plugin instead.

Do I need to modify my native iOS project?

No, the plugin injects the home indicator override into the Capacitor bridge view controller automatically. You do not need to subclass CAPBridgeViewController or edit your AppDelegate.

Is the hidden state persisted across app restarts?

No, the state managed by the plugin is kept in memory only and resets to shown when the app is restarted. If your app should always hide the home indicator, call hide() again after your app relaunches.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Android Edge-to-Edge Support: Support edge-to-edge display on Android with features like setting the status bar and navigation bar color.
• Navigation Bar: Set the background color and button style of the Android navigation bar.
• Screen Orientation: Lock and unlock the screen orientation.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.