Skip to content
Capgo

Getting Started

  1. Install the package

    Terminal window
    npm i @capgo/capacitor-navigation-bar

  2. Sync with native projects

    Terminal window
    npx cap sync

  3. Configure the plugin

    Minimum Requirements:

    • Android 5.0 (API level 21) or higher
    • The plugin only works on Android devices

    No additional setup required in AndroidManifest.xml.

  4. Advanced usage

    import { NavigationBar } from '@capgo/capacitor-navigation-bar';
    

    export class ThemeService {
      // Set transparent navigation bar
      async setTransparent() {
        await NavigationBar.setColor({
          color: '#00000000', // Transparent
          darkButtons: true
        });
      }
    

      // Match app theme
      async matchAppTheme(primaryColor: string, isLight: boolean) {
        await NavigationBar.setColor({
          color: primaryColor,
          darkButtons: isLight
        });
      }
    

      // Get current navigation bar color
      async getCurrentColor() {
        const result = await NavigationBar.getColor();
        console.log('Current color:', result.color);
        return result.color;
      }
    

      // Reset to default
      async resetToDefault() {
        await NavigationBar.setColor({
          color: '#000000',
          darkButtons: false
        });
      }
    }

  5. Integration with app lifecycle

    import { App } from '@capacitor/app';
    import { NavigationBar } from '@capgo/capacitor-navigation-bar';
    

    // Update navigation bar on app state changes
    App.addListener('appStateChange', async ({ isActive }) => {
      if (isActive) {
        // Restore your app's navigation bar color
        await NavigationBar.setColor({
          color: '#YourAppColor',
          darkButtons: true
        });
      }
    });
    

    // Handle theme changes
    window.matchMedia('(prefers-color-scheme: dark)')
      .addEventListener('change', async (e) => {
        await NavigationBar.setColor({
          color: e.matches ? '#121212' : '#FFFFFF',
          darkButtons: !e.matches
        });
      });

API Reference

Methods

setColor(options: ColorOptions)

Set the navigation bar color and button style.

Parameters:

  • options: Configuration object
    • color: string - Hex color code (e.g., ‘#FF0000’)
    • darkButtons: boolean - Use dark buttons (true) or light buttons (false)

Returns: Promise<void>

getColor()

Get the current navigation bar color.

Returns: Promise<{ color: string }>

Interfaces

interface ColorOptions {
  color: string;      // Hex color code
  darkButtons: boolean; // Button style
}


interface ColorResult {
  color: string;      // Current hex color
}

Platform Notes

Android

  • Requires Android 5.0 (API level 21) or higher
  • Color changes are immediate
  • Transparent colors are supported (use alpha channel)
  • The navigation bar might not be visible on devices with gesture navigation

iOS

  • This plugin has no effect on iOS devices
  • iOS does not provide APIs to customize the system navigation

Common Use Cases

  1. Brand Consistency: Match navigation bar with your app’s primary color
  2. Theme Support: Adapt to light/dark themes dynamically
  3. Immersive Experiences: Use transparent navigation for full-screen content
  4. Status Indication: Change color to indicate app states (recording, errors, etc.)

Best Practices

  1. Color Contrast: Ensure sufficient contrast between navigation bar and buttons

    // Good contrast examples
    setColor({ color: '#FFFFFF', darkButtons: true });  // White bar, dark buttons
    setColor({ color: '#000000', darkButtons: false }); // Black bar, light buttons

  2. Theme Consistency: Update navigation bar when theme changes

  3. Accessibility: Consider users with visual impairments when choosing colors

  4. Performance: Avoid frequent color changes that might distract users

Troubleshooting

Navigation bar not changing:

  • Verify the device is running Android 5.0+
  • Check if the device has gesture navigation enabled
  • Ensure color format is valid hex (e.g., ‘#FF0000’)

Buttons not visible:

  • Check the darkButtons parameter matches your background color
  • Light backgrounds need darkButtons: true
  • Dark backgrounds need darkButtons: false

Color appears different:

  • Some Android versions may modify the color slightly
  • Use fully opaque colors for best results