Navigation Bar
@ethion/capacitor-navigation-bar
Capacitor plugin for Navigation Bar manipulation.
## Version
| Platform | Version | Remarks |
| ----------- | ------------------------------------------- | --------------------------------------------------------------- |
| Capacitor | V7+ | Supports older versions of capacitor e.g V5+, V6+ |
## Maintainers
| Maintainer | GitHub | Website |
| ----------- | ------------------------------------------- | --------------------------------------------------------------- |
| Jeffrey Aboh | [jeffreyaboh](https://github.com/jeffreyaboh) | [Jeffrey Aboh](https://jeffreyaboh.co.uk) |
## Install
```bash
npm install @ethion/capacitor-navigation-bar
npx cap sync
```
## Configuration
No configuration required for this plugin.
## API
* [`show()`](#show)
* [`hide()`](#hide)
* [`setColor(...)`](#setcolor)
* [`setTransparency(...)`](#settransparency)
* [`getColor()`](#getcolor)
* [`addListener(NavigationBarPluginEvents.SHOW, ...)`](#addlistenernavigationbarplugineventsshow-)
* [`addListener(NavigationBarPluginEvents.HIDE, ...)`](#addlistenernavigationbarplugineventshide-)
* [`addListener(NavigationBarPluginEvents.COLOR_CHANGE, ...)`](#addlistenernavigationbarplugineventscolor_change-)
* [Interfaces](#interfaces)
* [Enums](#enums)
### show()
```typescript
show() => Promise
```
Display the navigation bar.
--------------------
### hide()
```typescript
hide() => Promise
```
Hide the navigation bar.
--------------------
### setColor(...)
```typescript
setColor(options: ColorParameters) => Promise
```
Change the color of the navigation bar.
*Support alpha hexadecimal numbers.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| **`options`** | ColorParameters |
--------------------
### setTransparency(...)
```typescript
setTransparency(options: { isTransparent: boolean; }) => Promise
```
Set the Transparency
| Param | Type |
| ------------- | ---------------------------------------- |
| **`options`** | { isTransparent: boolean; } |
--------------------
### getColor()
```typescript
getColor() => Promise<{ color: string; }>
```
Gets the current color of the navigation bar in Hexadecimal.
**Returns:** Promise<{ color: string; }>
--------------------
### addListener(NavigationBarPluginEvents.SHOW, ...)
```typescript
addListener(event: NavigationBarPluginEvents.SHOW, listenerFunc: () => void) => Promise
```
Event fired after navigation bar is displayed
| Param | Type | Description |
| ------------------ | ------------------------------------------------------------------------------------ | ----------- |
| **`event`** | NavigationBarPluginEvents.SHOW | The event |
| **`listenerFunc`** | () => void | Callback |
**Returns:** Promise<PluginListenerHandle>
--------------------
### addListener(NavigationBarPluginEvents.HIDE, ...)
```typescript
addListener(event: NavigationBarPluginEvents.HIDE, listenerFunc: () => void) => Promise
```
Event fired after navigation bar is hidden
| Param | Type | Description |
| ------------------ | ------------------------------------------------------------------------------------ | ----------- |
| **`event`** | NavigationBarPluginEvents.HIDE | The event |
| **`listenerFunc`** | () => void | Callback |
**Returns:** Promise<PluginListenerHandle>
--------------------
### addListener(NavigationBarPluginEvents.COLOR_CHANGE, ...)
```typescript
addListener(event: NavigationBarPluginEvents.COLOR_CHANGE, listenerFunc: (returnObject: { color: string; }) => void) => Promise
```
Event fired after navigation bar color is changed
| Param | Type | Description |
| ------------------ | -------------------------------------------------------------------------------------------- | ----------- |
| **`event`** | NavigationBarPluginEvents.COLOR_CHANGE | The event |
| **`listenerFunc`** | (returnObject: { color: string; }) => void | Callback |
**Returns:** Promise<PluginListenerHandle>
--------------------
### Interfaces
#### ColorParameters
| Prop | Type | Description |
| ----------------- | -------------------- | ------------------------------------------------------------------------- |
| **`color`** | string | Sets the new color of the navigation bar. |
| **`darkButtons`** | boolean | Sets whether the default navigation bar buttons should be black or white. |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| **`remove`** | () => Promise<void> |
### Enums
#### NavigationBarPluginEvents
| Members | Value | Description |
| ------------------ | ---------------------------- | -------------------------------------------- |
| **`SHOW`** | 'onShow' | Called after the navigation bar is displayed |
| **`HIDE`** | 'onHide' | Called after navigation bar is hidden |
| **`COLOR_CHANGE`** | 'onColorChange' | Called after navigation bar color is changed |
## Usage Example
```typescript
import { NavigationBar, NavigationBarPluginEvents } from '@ethion/capacitor-navigation-bar';
// Show the navigation bar
await NavigationBar.show();
// Hide the navigation bar
await NavigationBar.hide();
// Set navigation bar color
await NavigationBar.setColor({ color: '#FF0000', darkButtons: true });
// Set transparency
await NavigationBar.setTransparency({ isTransparent: true });
// Listen for events
NavigationBar.addListener(NavigationBarPluginEvents.SHOW, () => {
console.log('Navigation bar is shown');
});
```
## Compatibility
| Capacitor Version | Supported |
|-------------------|-----------|
| 7.x | Yes |
| 6.x | Yes |
| 5.x | Yes |
| 4.x | Yes |
## Migrating from Other Plugins
If you previously used `capacitor-navigationbar` or other similar plugins, switch to this package for active support and compatibility with the latest Capacitor versions. Update your imports and installation commands as shown above.
## Related Plugins
For status bar control, see the official Capacitor plugin: [@capacitor/status-bar](https://capacitorjs.com/docs/apis/status-bar)