TopNavBar

The navigation bar sits at the top of every non-root screen. It orients users with a title, provides a back action, and holds up to two icon actions relevant to the current context.

When to use: Every screen that is not a root tab. Detail screens, settings screens, modals with their own navigation structure.

When not to use: Root tabs (Home, Explore, Profile) — those use a tab bar. Modals that use a sheet presentation with a built-in handle — the handle implies dismissal without needing an explicit back button.

Import

import { TopNavBar } from '@/components';
import { MagnifyingGlass, Sliders } from 'phosphor-react-native';

Usage

<TopNavBar
  title="Settings"
  onBack={router.back}
  rightActions={[
    { icon: MagnifyingGlass, onPress: openSearch, accessibilityLabel: 'Search' },
  ]}
/>

Props

Prop	Type	Default	Description
title	string	—	Screen title (required)
onBack	() => void	—	Back action; omit on root screens
rightActions	Array<{ icon, onPress, accessibilityLabel }>	[]	Up to 2 icon actions on the right
testID	string	—

rightActions item shape

Prop	Type	Description
icon	PhosphorIconComponent	Icon to display
onPress	() => void	Press handler
accessibilityLabel	string	Screen reader label (required)

Examples

// Back only
<TopNavBar title="Profile" onBack={router.back} />

// Back + one action
<TopNavBar
  title="Inbox"
  onBack={router.back}
  rightActions={[
    { icon: Pencil, onPress: compose, accessibilityLabel: 'Compose' },
  ]}
/>

// Back + two actions
<TopNavBar
  title="Photos"
  onBack={router.back}
  rightActions={[
    { icon: MagnifyingGlass, onPress: search, accessibilityLabel: 'Search' },
    { icon: Sliders, onPress: filter, accessibilityLabel: 'Filter' },
  ]}
/>

// No back (root-level section screen)
<TopNavBar title="Dashboard" />

Do / Don’t

Do: Maximum 2 right actions — use a “more” overflow menu for additional actions.

Don’t: Use TopNavBar on root tabs — they typically have persistent tab bars.

Don’t: Put business logic in the nav bar. onBack should call router.back() or a navigation hook — not trigger API calls.

In a layout

TopNavBar is used by SettingsLayout internally. You normally don’t need to render it directly unless building a custom layout:

<SettingsLayout title="Account" onBack={router.back}>
  {/* TopNavBar is rendered by the layout */}
  <SettingsGroup rows={rows} />
</SettingsLayout>

Related

• SettingsLayout — template that wraps TopNavBar + scrollable content
• IconButton — the atom used for right actions