Expo NavigationBar

useVisibility()

React hook that statefully updates with the visibility of the system navigation bar.

Example

function App() {
  const visibility = NavigationBar.useVisibility()
  // React Component...
}

Returns

• NavigationBarVisibility | null

Visibility of the navigation bar, null during async initialization.

NavigationBar.getBackgroundColorAsync()

Gets the navigation bar's background color.

Example

const color = await NavigationBar.getBackgroundColorAsync();

Returns

• Promise<ColorValue>

Current navigation bar color in hex format. Returns #00000000 (transparent) on unsupported platforms (iOS, web).

NavigationBar.getBehaviorAsync()

Gets the behavior of the status and navigation bars when the user swipes or touches the screen.

Example

await NavigationBar.getBehaviorAsync()

Returns

• Promise<NavigationBarBehavior>

Navigation bar interaction behavior. Returns inset-touch on unsupported platforms (iOS, web).

NavigationBar.getBorderColorAsync()

Gets the navigation bar's top border color, also known as the "divider color".

Example

const color = await NavigationBar.getBorderColorAsync();

Returns

• Promise<ColorValue>

Navigation bar top border color in hex format. Returns #00000000 (transparent) on unsupported platforms (iOS, web).

NavigationBar.getButtonStyleAsync()

Gets the navigation bar's button color styles.

Example

const style = await NavigationBar.getButtonStyleAsync();

Returns

• Promise<NavigationBarButtonStyle>

Navigation bar foreground element color settings. Returns light on unsupported platforms (iOS, web).

NavigationBar.getVisibilityAsync()

Get the navigation bar's visibility.

Example

const visibility = await NavigationBar.getVisibilityAsync("hidden");

Returns

• Promise<NavigationBarVisibility>

Navigation bar's current visibility status. Returns hidden on unsupported platforms (iOS, web).

NavigationBar.setBackgroundColorAsync(color)

Changes the navigation bar's background color.

Example

NavigationBar.setBackgroundColorAsync("white");

Returns

• Promise<void>

NavigationBar.setBehaviorAsync(behavior)

Sets the behavior of the status bar and navigation bar when they are hidden and the user wants to reveal them.

For example, if the navigation bar is hidden (setVisibilityAsync(false)) and the behavior is 'overlay-swipe', the user can swipe from the bottom of the screen to temporarily reveal the navigation bar.

• 'overlay-swipe': Temporarily reveals the System UI after a swipe gesture (bottom or top) without insetting your App's content.
• 'inset-swipe': Reveals the System UI after a swipe gesture (bottom or top) and insets your App's content (Safe Area). The System UI is visible until you explicitly hide it again.
• 'inset-touch': Reveals the System UI after a touch anywhere on the screen and insets your App's content (Safe Area). The System UI is visible until you explicitly hide it again.

Example

await NavigationBar.setBehaviorAsync('overlay-swipe')

Returns

• Promise<void>

NavigationBar.setBorderColorAsync(color)

Changes the navigation bar's border color.

Example

NavigationBar.setBorderColorAsync("red");

Returns

• Promise<void>

NavigationBar.setButtonStyleAsync(style)

Changes the navigation bar's button colors between white (light) and a dark gray color (dark).

Example

NavigationBar.setButtonStyleAsync("light");

Returns

• Promise<void>

NavigationBar.setPositionAsync(position)

Sets positioning method used for the navigation bar (and status bar). Setting position absolute will float the navigation bar above the content, whereas position relative will shrink the screen to inline the navigation bar.

When drawing behind the status and navigation bars, ensure the safe area insets are adjusted accordingly.

Example

// enables edge-to-edge mode
await NavigationBar.setPositionAsync('absolute')
// transparent backgrounds to see through
await NavigationBar.setBackgroundColorAsync('#ffffff00')

Returns

• Promise<void>

NavigationBar.setVisibilityAsync(visibility)

Set the navigation bar's visibility.

Example

NavigationBar.setVisibilityAsync("hidden");

Returns

• Promise<void>

NavigationBar.unstable_getPositionAsync()

Whether the navigation and status bars float above the app (absolute) or sit inline with it (relative). This value can be incorrect if androidNavigationBar.visible is used instead of the config plugin position property.

This method is unstable because the position can be set via another native module and get out of sync. Alternatively, you can get the position by measuring the insets returned by react-native-safe-area-context.

Example

await NavigationBar.unstable_getPositionAsync()

Returns

• Promise<NavigationBarPosition>

Navigation bar positional rendering mode. Returns relative on unsupported platforms (iOS, web).

NavigationBar.addVisibilityListener(listener)

Observe changes to the system navigation bar. Due to platform constraints, this callback will also be triggered when the status bar visibility changes.

Example

NavigationBar.addVisibilityListener(({ visibility }) => {
  // ...
});

Returns

• Subscription