@webnativellc/capacitor-navigation-bar
Capacitor plugin for Navigation Bar manipulation.
| Maintainer | GitHub | Social |
|---|---|---|
| Hugo Tomazi | hugotomazi | @hugotomazi |
| Damian Tarnawsky | damiant | @damiant.bsky.social |
npm install @webnativellc/capacitor-navigation-bar
npx cap syncNo configuration required for this plugin.
show()hide()setColor(...)setTransparency(...)getColor()addListener(NavigationBarPluginEvents.SHOW, ...)addListener(NavigationBarPluginEvents.HIDE, ...)addListener(NavigationBarPluginEvents.COLOR_CHANGE, ...)- Interfaces
- Enums
show() => Promise<void>Display the navigation bar.
Shows the navigation bar if it was previously hidden. This method will animate the navigation bar back into view.
hide() => Promise<void>Hide the navigation bar.
Hides the navigation bar from view. This is useful for immersive experiences like games, video players, or full-screen content. The bar can be temporarily revealed by swiping from the bottom of the screen.
setColor(options: ColorParameters) => Promise<void>Change the color of the navigation bar.
Sets a custom background color for the navigation bar. Supports standard hex colors as well as alpha (transparency) values for semi-transparent bars.
| Param | Type | Description |
|---|---|---|
options |
ColorParameters |
- Color configuration options |
setTransparency(options: { isTransparent: boolean; }) => Promise<void>Set the transparency of the navigation bar.
Makes the navigation bar fully transparent, allowing content to be displayed beneath it. This is useful for creating immersive, edge-to-edge layouts.
| Param | Type | Description |
|---|---|---|
options |
{ isTransparent: boolean; } |
- Transparency configuration |
getColor() => Promise<{ color: string; }>Gets the current color of the navigation bar.
Retrieves the current background color of the navigation bar as a hexadecimal string. This is useful for saving and restoring the navigation bar state.
Returns: Promise<{ color: string; }>
addListener(event: NavigationBarPluginEvents.SHOW, listenerFunc: () => void) => Promise<PluginListenerHandle>Listen for navigation bar show events.
Registers a callback that will be invoked whenever the navigation bar is displayed. This can occur when calling show() or through system interactions.
| Param | Type | Description |
|---|---|---|
event |
NavigationBarPluginEvents.SHOW |
- The event type (NavigationBarPluginEvents.SHOW) |
listenerFunc |
() => void |
- Callback function to execute when the event fires |
Returns: Promise<PluginListenerHandle>
addListener(event: NavigationBarPluginEvents.HIDE, listenerFunc: () => void) => Promise<PluginListenerHandle>Listen for navigation bar hide events.
Registers a callback that will be invoked whenever the navigation bar is hidden. This can occur when calling hide() or through system interactions.
| Param | Type | Description |
|---|---|---|
event |
NavigationBarPluginEvents.HIDE |
- The event type (NavigationBarPluginEvents.HIDE) |
listenerFunc |
() => void |
- Callback function to execute when the event fires |
Returns: Promise<PluginListenerHandle>
addListener(event: NavigationBarPluginEvents.COLOR_CHANGE, listenerFunc: (returnObject: { color: string; }) => void) => Promise<PluginListenerHandle>Listen for navigation bar color change events.
Registers a callback that will be invoked whenever the navigation bar color is changed. The callback receives the new color value.
| Param | Type | Description |
|---|---|---|
event |
NavigationBarPluginEvents.COLOR_CHANGE |
- The event type (NavigationBarPluginEvents.COLOR_CHANGE) |
listenerFunc |
(returnObject: { color: string; }) => void |
- Callback function to execute when the event fires, receives an object with the new color |
Returns: Promise<PluginListenerHandle>
| Prop | Type | Description | Default |
|---|---|---|---|
color |
string |
Sets the new color of the navigation bar. Accepts hexadecimal color values in the following formats: - 6-character hex: '#RRGGBB' (e.g., '#FF0000' for red) - 8-character hex: '#AARRGGBB' (e.g., '#80FF0000' for semi-transparent red) The alpha channel (first two characters in 8-character format) controls transparency: - '00' = fully transparent - '80' = 50% transparent - 'FF' = fully opaque | |
darkButtons |
boolean |
Sets whether the default navigation bar buttons should be black or white. This option controls the color of the system navigation buttons (back, home, recents) to ensure they remain visible against your chosen background color. - true: Uses dark/black buttons (recommended for light backgrounds) - false: Uses light/white buttons (recommended for dark backgrounds) - undefined: System determines button color automatically |
false |
| Prop | Type |
|---|---|
remove |
() => Promise<void> |
| Members | Value | Description |
|---|---|---|
SHOW |
'onShow' |
Called after the navigation bar is displayed. This event fires when the navigation bar becomes visible, either through a programmatic call to show() or through system interactions (e.g., user swiping to reveal the bar). |
HIDE |
'onHide' |
Called after the navigation bar is hidden. This event fires when the navigation bar becomes hidden, either through a programmatic call to hide() or through system interactions. |
COLOR_CHANGE |
'onColorChange' |
Called after the navigation bar color is changed. This event fires when the navigation bar background color is updated through a call to setColor(). The event callback receives the new color value. |
- ios: Add Swift Package Manager (SPM) support (#XX)
- ci: Update CI workflow to match Capacitor Community best practices
- Upgraded Node.js from 18 to 20
- Upgraded Java from 17 to 21
- Updated GitHub Actions to latest versions (v4)
- Added dedicated lint job
- Updated to macOS 15 runner
- Switched to Zulu Java distribution
- Added comprehensive verify scripts for iOS, Android, and Web platforms
- Improved code quality tooling with ESLint, Prettier, and SwiftLint integration