Technical Documentation: wix/react-native-navigation

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

React Native Navigation

React Native Navigation provides 100% native platform navigation on both iOS and Android for React Native apps. The JavaScript API is simple and cross-platform - just install it in your app and give your users the native feel they deserve. Ready to get started? Check out the docs.

Quick Links

• Documentation
• Changelog
• Stack Overflow
• Chat with us
• Contributing

Requirements

Apps using React Native Navigation may target iOS 11 and Android 5.0 (API 21). You may use Windows, macOS or Linux as your development operating system.

Installation

As react-native-navigation is a native navigation library - integrating it into your app will require editing native files. Follow the installation guides in the documentation.

Releases Copy Chapter

Repository administrators: see the release runbook for manual releases,
npm trusted publishing setup, and recovery.

Overview (`playground/README.md`) Copy Section

Navigation Playground

A local example project using react-native-navigation.
The target app for all e2e tests.

Overview (`test-app/README.md`) Copy Section

This is a new React Native project, bootstrapped using @react-native-community/cli.

Getting Started

Note: Make sure you have completed the Set Up Your Environment guide before proceeding.

Step 1: Start Metro Copy Chapter

First, you will need to run Metro, the JavaScript build tool for React Native.

To start the Metro dev server, run the following command from the root of your React Native project:

# Using npm
npm start

# OR using Yarn
yarn start

Step 2: Build and run your app Copy Chapter

With Metro running, open a new terminal window/pane from the root of your React Native project, and use one of the following commands to build and run your Android or iOS app:

Android Copy Section

# Using npm
npm run android

# OR using Yarn
yarn android

iOS Copy Section

For iOS, remember to install CocoaPods dependencies (this only needs to be run on first clone or after updating native deps).

The first time you create a new project, run the Ruby bundler to install CocoaPods itself:

bundle install

Then, and every time you update your native dependencies, run:

bundle exec pod install

For more information, please visit CocoaPods Getting Started guide.

# Using npm
npm run ios

# OR using Yarn
yarn ios

If everything is set up correctly, you should see your new app running in the Android Emulator, iOS Simulator, or your connected device.

This is one way to run your app — you can also build it directly from Android Studio or Xcode.

Step 3: Modify your app Copy Chapter

Now that you have successfully run the app, let's make changes!

Open App.tsx in your text editor of choice and make some changes. When you save, your app will automatically update and reflect these changes — this is powered by Fast Refresh.

When you want to forcefully reload, for example to reset the state of your app, you can perform a full reload:

• Android: Press the R key twice or select "Reload" from the Dev Menu, accessed via Ctrl + M (Windows/Linux) or Cmd ⌘ + M (macOS).
• iOS: Press R in iOS Simulator.

Congratulations! :tada: Copy Chapter

You've successfully run and modified your React Native App. :partying_face:

Now what? Copy Section

• If you want to add this new React Native code to an existing application, check out the Integration guide.
• If you're curious to learn more about React Native, check out the docs.

Troubleshooting

If you're having issues getting the above steps to work, see the Troubleshooting page.

Learn More

To learn more about React Native, take a look at the following resources:

• React Native Website - learn more about React Native.
• Getting Started - an overview of React Native and how setup your environment.
• Learn the Basics - a guided tour of the React Native basics.
• Blog - read the latest official React Native Blog posts.
• @facebook/react-native - the Open Source; GitHub repository for React Native.

RELEASING (`docs/RELEASING.md`) Copy Section

Releasing React Native Navigation

The Release workflow
is the only supported npm publisher. Repository admins start it manually on master.
Both regular releases and snapshots use npm trusted publishing with GitHub OIDC.
Buildkite runs native tests; it no longer versions or publishes packages. Its expired npm
credentials must not be renewed as a fallback.

One-time configuration Copy Chapter

A repository admin and an npm package administrator must complete these steps before
enabling publication. Creating or merging the workflow does not configure npm trust.

1. Create the GitHub environment npm-release. Under deployment branches and tags,
   select only the branch master. Protect master and review changes to release
   workflows and helpers. Required environment reviewers are optional; enabling them
   introduces approvals for the record, publish, and finalize jobs.

2. In the npm settings for react-native-navigation, add a GitHub Actions trusted publisher:

   Field	Value
   Organization	wix
   Repository	react-native-navigation
   Workflow filename	release.yml
   Environment	npm-release
   Allowed action	Direct npm publish

   Explicitly allow direct publication: a stage-only configuration cannot complete this
   workflow. Standalone npm dist-tag permission is not needed. See
   npm trusted publishing.

3. Enable GitHub Actions for this repository. Check Wix's Actions policy permits the pinned checkout, setup-node, upload-artifact,
   and download-artifact actions. Allow workflow-created pull requests. Ensure existing
   repository rules permit version branches and release tags without a bypass.

4. Check the GitHub commit status buildkite/react-native-navigation represents all
   Android/iOS lanes in .buildkite/pipeline.sh. It must finish successfully on the
   exact master commit selected by the release run. The status creator must match
   the Buildkite app ID/login pinned in scripts/release/rnn.cjs. A failed, absent, or pending status
   blocks real publication, including snapshots. A dry run reports it without publishing.

5. Verify a dry run and inspect its artifact. Then set the repository Actions variable
   RELEASE_PUBLISH_ENABLED to true. Without it, publish and resume fail closed.

6. Run an intentional snapshot publication and verify the npm version, integrity,
   provenance, and snapshot dist-tag. Confirm that latest did not change.

7. Remove obsolete release-only npm secret injection and restrict traditional token
   publishing in npm's package settings. Do not renew expired tokens. A shared credential
   must not be revoked until its other consumers have been identified.

No npm write token is needed in GitHub. GITHUB_TOKEN performs repository bookkeeping;
only the publish job has id-token: write. Publishing runs on a GitHub-hosted Ubuntu
runner. The workflow uses Node 24.22.1, including npm 11.19.1; update this tested pair
together. Older npm releases can execute prepare during npm pack --ignore-scripts.

Start a release Copy Chapter

Open Actions → Release → Run workflow, select master, and supply:

Examples:

• Stable: kind=release, version=8.9.1, npm_tag=latest.
• Prerelease: kind=release, version=8.9.0-rc.1, npm_tag=next.
• Snapshot: kind=snapshot, leave version empty, npm_tag=snapshot.

The selected version must be newer than npm latest. Build metadata such as +build.1
is intentionally unsupported. Snapshots use -snapshot.gha.<run_id>, with the
base derived from the greater of the source package version and npm latest. The
run attempt is not part of the version. Snapshots do not create tags, GitHub releases,
version PRs, or documentation changes.

Users with write access may see GitHub's Run workflow button, but both the original
actor and the user rerunning/resuming the workflow must have repository-admin permission.
The workflow rechecks authorization before every job that changes external state.

What the workflow does Copy Chapter

1. Records the exact source SHA, chosen version/channel, and native CI result.
2. Installs the locked Yarn dependencies, changes release metadata, builds JS and
   declarations with Bob, and runs JavaScript and release-helper tests on Linux.
3. Optionally installs the locked website dependencies, generates the requested docs
   version, and builds the site. Removal requires an existing numeric version; replacing
   an existing version requires explicitly selecting that same version for removal.
4. Creates a local release commit containing only the version and optional versioned
   docs, then packs the already built package. Package contents and exported paths are
   checked. Android/iOS sources ship in the package; this job does not compile native apps.
5. Uploads a versioned manifest, the tarball, release notes, and a Git bundle as
   release-<run_id>-<run_attempt>. A dry run ends here with no external release mutations.
6. For real releases, persists ci/update-version-<version>, then publishes the verified
   tarball using OIDC. The publisher does not install project dependencies or rebuild it.
7. Verifies npm integrity, tags the source commit on master with the bare version (for example
   8.9.1), creates a GitHub release, and opens a version/documentation PR with the
   release label. An existing PR template is included with its checkboxes left for review.

Release notes include merged PRs from the preceding reachable stable tag through the
source commit. They preserve feature/enhancement/fix categories, platform groups, and
skip-changelog exclusions. No second gren invocation or timed retry is involved.

Review and merge the version PR after publication. Documentation deploys through the
existing documentation workflow after that merge. Events created with GITHUB_TOKEN do not
start Actions workflows, so Release checks will not run on the version PR; Buildkite still
builds it through its webhook. Inspect the PR's checks before merging. The release workflow
does not invoke engine notification.

Resume a partial release Copy Chapter

Use Re-run failed jobs when the original run still has its preparation outputs, or
dispatch operation=resume with source_run_id set to the original publish run.
Other release inputs are ignored in resume mode. Do not enter a different version to
recover from a GitHub or network error.

Recovery validates the upstream workflow identity, source SHA, native CI, artifact
integrity, release commit, and package metadata. It downloads the saved artifacts and
does not rebuild against the current branch. If the version is still absent from npm and
master has advanced, re-run the original publishing run instead of dispatching a new
resume run: npm provenance must identify the source commit that built the package. A new
resume dispatch may finish GitHub bookkeeping for an already published matching tarball.

Artifacts request 90-day retention, subject to organization limits. Retain artifacts until
the version PR is merged and the release is verified. After artifact loss, an admin must
investigate the existing registry version and persisted release branch manually; do not
reconstruct and publish different bytes under the same version or automatically fall back
to the old pipeline. npm and GitHub do not provide a cross-service atomic transaction.

The concurrency group serializes all release attempts. GitHub may replace a pending run
when another dispatch is queued; it does not cancel the running publisher. Check each run's
state rather than assuming every click is queued indefinitely.

Validate changes to the release tooling Copy Chapter

With Node 24.22.1 and npm 11.19.1:

node --test scripts/release/*.test.cjs
node .yarn/releases/yarn-4.12.0.cjs install --immutable
node .yarn/releases/yarn-4.12.0.cjs prepare
node .yarn/releases/yarn-4.12.0.cjs test-js
RELEASE_DIR=/tmp/rnn-package node scripts/release/index.cjs pack-check

pack-check only prepares and inspects a local tarball. The read-only Release checks
workflow runs the tests and clean Linux package check on PRs. A real OIDC publication
still needs the default-branch workflow and the npm/GitHub configuration above.

Removed release paths and retained consumers Copy Chapter

The Buildkite release form, publishing job, legacy scripts/release.js, gren config,
and root/playground github-release-notes dependencies have been removed. Automatic
Buildkite snapshots are replaced by manual snapshots. Native Buildkite testing remains.

Outside the repository, remove obsolete release schedules/hooks and release-only
NPM_TOKEN/NPM_EMAIL injection. Inspect any old Jenkins configuration referenced by
historical setup; the old README badge alone does not prove an active publisher exists.

Keep the tracked registry-only .npmrc, documentation deployment's GH_PAGES_DEPLOY,
and any Git credential still used by scripts/test-snapshot.js to record reference images.
Do not delete shared secrets merely because the old publisher also used them.

For the next repository, use the migration checklist.

Release Migration Checklist (`docs/release-migration-checklist.md`) Copy Section

Migrating another repository to trusted publishing

RNN establishes a release contract: admin dispatch, explicit versions, immutable build
artifacts, OIDC publication, and recovery of the same package bytes. Copy the contract
before extracting shared code. Repository-specific build and package policy lives in
scripts/release/rnn.cjs; the current workflow and manifest validator intentionally accept
only RNN. Another repository must implement and test its own adapter and authorization.

Inventory before changing a publisher Copy Chapter

• Read the target repository's instructions and release tests.
• List every publishable package, its source directory, version authority, dist-tags,
  Git tag convention, and dependency relationship to the other packages.
• Trace release-trigger inputs, lifecycle hooks, generated artifacts, documentation,
  release notes, PRs, and any native packaging commands.
• Identify native CI evidence by exact commit. Distinguish the tools needed to produce
  the npm package from tools needed only for testing.
• Inventory CI schedules, webhooks, release credentials, and other consumers of shared
  credentials. A release script deletion alone does not remove an external trigger.

Implement the repository adapter Copy Chapter

• Keep a stable repository-local release.yml entry point and protected environment.
• Configure allowed branches, admin authorization, packages, runners, build commands,
  expected tarball contents, version/dependency rewrites, and tag naming.
• Resolve the complete package/version plan before the first publish. Use an ordered
  package list and store each package's integrity in the manifest.
• Build without npm publishing credentials. Native preparation can use separate runner
  jobs; the OIDC publisher must run on a supported GitHub-hosted runner.
• Preserve artifacts and verify their original workflow/source identity during recovery.
• Publish each package only if absent. If already present, require matching integrity.
  Never bump all versions after a partial publish. Multi-package publication is not atomic.
• Register npm trust separately for every package. If introducing reusable workflows,
  check npm's caller-workflow identity rules and grant the required OIDC permissions at
  the caller/callee boundaries. Pin shared implementations to reviewed commit SHAs.

Known differences from RNN Copy Chapter

UI-lib's starting points are scripts/release/release.js, releaseUtils.js, and the
existing release-script tests. Its dependency rewrite must use the planned or verified
published native version, including when only one package needs publication.

Detox's starting points are scripts/ci.release.js, scripts/utils/publishNewVersion.js,
scripts/ci.android-release.js, scripts/ci.ios-release.sh, and the Buildkite release
pipelines. Android packaging invokes the SDK and Gradle. Resolve the current iOS packaging
entry point before replacing its artifact download flow. Do not assume RNN's Linux-only
package preparation applies to Detox.

Clean up and verify Copy Chapter

• Delete obsolete publishing jobs, forms, entry points, credential-writing helpers,
  retry-by-version-increment code, dead dependencies, and stale instructions.
• Preserve native tests, useful history, documentation deployment, and shared credentials
  with remaining consumers.
• Test dry-run non-mutation, unauthorized dispatch/rerun, version/channel validation,
  source CI gating, package completeness, and lost-response/partial-publication recovery.
• Verify clean runner builds, then a deliberate prerelease/snapshot using real OIDC.
• Document one-time configuration, remaining infrastructure cleanup, and artifact-loss
  recovery. Expired token-based publishers are not an automatic fallback.

Extract the common publisher, authorization, and artifact-state helpers only after a
second adopter confirms their interface. Build commands, package graphs, documentation,
and version conventions should remain repository-specific.

Api Api Component (`website/docs/api/api-component.mdx`) Copy Section

id: component title: Component sidebar_label: Component Copy Chapter

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

`registerComponent` Copy Chapter

Every screen component in your app must be registered with a unique name. The component itself is a traditional React component extending React.Component or React.PureComponent. It can also be a HOC to provide context (or a Redux store) or a functional component. Similar to React Native's AppRegistry.registerComponent.

Parameters

Examples

Registering a component

Navigation.registerComponent(`navigation.playground.WelcomeScreen`, () => WelcomeScreen);

Registering a component wrapped with Providers

import { Provider } from 'react-redux';
const store = createStore();

Navigation.registerComponent(`navigation.playground.MyScreen`, () => (props) =>
  <Provider store={store}>
    <MyScreen {...props} />
  </Provider>,
  () => MyScreen)
);

`setLazyComponentRegistrator` Copy Chapter

Pass a function that will allow you to register a component lazily. When encountering an unknown component name, this function will be called, giving you a chance to register the component before an error is thrown.

Parameters

Example

Navigation.setLazyComponentRegistrator((componentName) => {
  if (componentName === 'navigation.playground.LazyScreen') {
    Navigation.registerComponent(Screens.LazilyRegisteredScreen, () => LazyScreen);
  }
});

`updateProps` Copy Chapter

Update props of a component registered with registerComponent. Updating props triggers the component lifecycle methods related to updating.

Parameters

Example

Navigation.updateProps('MY_COMPONENT', {
  // props to pass to the component
};

:::important
updateProps is called with a componentId. This is the same unique id components have in props. Don't confuse it with the componentName we use when registering components with Navigation.registerComponent.
:::

Api Api Events (`website/docs/api/api-events.mdx`) Copy Section

id: events title: Events sidebar_label: Events Copy Chapter

onAppLaunched Copy Chapter

Called once the app is launched. Used to set the initial layout of the Application - after that the app is ready for user interaction.

const appLaunchedListener = Navigation.events().registerAppLaunchedListener(() => {});

RNN automatically unsubscribes components when they unmount, therefore unsubscribing isn't actually mandatory if you subscribed in componentDidMount.

But you can use the following method to unsubscribe manually:

appLaunchedListener.remove();

componentWillAppear Copy Chapter

Called each time before this component appears on the screen (notifies that the component view is about to be added to the view hierarchy).

class MyComponent extends Component {
  componentDidMount() {
    this.navigationEventListener = Navigation.events().bindComponent(this);
  }

  componentWillUnmount() {
    // Not mandatory
    if (this.navigationEventListener) {
      this.navigationEventListener.remove();
    }
  }

  componentWillAppear() {}
}

componentDidAppear Copy Chapter

Called each time this component appears on the screen (attached to the view hierarchy).

class MyComponent extends Component {
  componentDidMount() {
    this.navigationEventListener = Navigation.events().bindComponent(this);
  }

  componentWillUnmount() {
    // Not mandatory
    if (this.navigationEventListener) {
      this.navigationEventListener.remove();
    }
  }

  componentDidAppear() {}
}

This event can be observed globally as well:

// Subscribe
const screenEventListener = Navigation.events().registerComponentDidAppearListener(({ componentId, componentName, passProps }) => {

});
...
// Unsubscribe
screenEventListener.remove();

componentDidDisappear Copy Chapter

Called each time this component disappears from the screen (detached from the view hierarchy).

class MyComponent extends Component {
  componentDidMount() {
    this.navigationEventListener = Navigation.events().bindComponent(this);
  }

  componentWillUnmount() {
    // Not mandatory
    if (this.navigationEventListener) {
      this.navigationEventListener.remove();
    }
  }

  componentDidDisappear() {}
}

This event can be observed globally as well:

// Subscribe
const screenEventListener = Navigation.events().registerComponentDidDisappearListener(({ componentId, componentName }) => {

});
...
// Unsubscribe
screenEventListener.remove();

registerCommandListener Copy Chapter

The commandListener is called whenever a Navigation command (i.e push, pop, showModal etc) is invoked.

// Subscribe
const commandListener = Navigation.events().registerCommandListener((name, params) => {

});
...
// Unsubscribe
commandListener.remove();

registerCommandCompletedListener Copy Chapter

Invoked when a command finishes executing in native. If the command contains animations, for example pushed screen animation, the listener is invoked after the animation ends.

// Subscribe
const commandCompletedListener = Navigation.events().registerCommandCompletedListener(({ commandId, completionTime, params }) => {

});
...
// Unsubscribe
commandCompletedListener.remove();

registerModalDismissedListener Copy Chapter

Invoked when a modal is dismissed.

// Subscribe
const modalDismissedListener = Navigation.events().registerModalDismissedListener(({ componentId, modalsDismissed }) => {

});
...
// Unsubscribe
modalDismissedListener.remove();

registerModalAttemptedToDismissListener(iOS 13+ only) Copy Chapter

Invoked only on iOS pageSheet modal when swipeToDismiss flag is set to true and modal was swiped down to dismiss.

// Subscribe
const modalAttemptedToDismissListener = Navigation.events().registerModalAttemptedToDismissListener(({ componentId }) => {

});
...
// Unsubscribe
modalAttemptedToDismissListener.remove();

registerScreenPoppedListener Copy Chapter

Invoked when the screen is popped.

// Subscribe
const screenPoppedListener = Navigation.events().registerScreenPoppedListener(({ componentId }) => {

});
...
// Unsubscribe
screenPoppedListener.remove();

registerBottomTabPressedListener Copy Chapter

Invoked when a bottom tab is pressed by the user, including when selectTabOnPress is false (the selected tab does not change).

// Subscribe
const bottomTabEventListener = Navigation.events().registerBottomTabPressedListener(({ tabIndex }) => {

});
...
// Unsubscribe
bottomTabEventListener.remove();

Works with custom bottom tab items on iOS and Android.

registerBottomTabSelectedListener Copy Chapter

Invoked when BottomTab is selected by a user.

// Subscribe
const bottomTabEventListener = Navigation.events().registerBottomTabSelectedListener(({ selectedTabIndex, unselectedTabIndex }) => {

});
...
// Unsubscribe
bottomTabEventListener.remove();

Works with custom bottom tab items on iOS and Android.

registerBottomTabLongPressedListener Copy Chapter

Invoked when BottomTab is long pressed by a user. iOS only. Not emitted for custom bottom tab items — long press is handled on the native tab bar, which is hidden when every tab uses bottomTab.component.

// Subscribe
const bottomTabEventListener = Navigation.events().registerBottomTabLongPressedListener(({ selectedTabIndex }) => {

});
...
// Unsubscribe
bottomTabEventListener.remove();

navigationButtonPressed event Copy Chapter

This event is emitted whenever a TopBar button is pressed by a user.

class MyComponent extends Component {
  componentDidMount() {
    this.navigationEventListener = Navigation.events().bindComponent(this);
  }

  componentWillUnmount() {
    // Unregistering listeners bound to components isn't mandatory since RNN handles the unregistration for you
    if (this.navigationEventListener) {
      this.navigationEventListener.remove();
    }
  }

  navigationButtonPressed({ buttonId }) {}
}

This event can be observed globally as well:

// Subscribe
const navigationButtonEventListener = Navigation.events().registerNavigationButtonPressedListener(({ buttonId }) => {

});
...
// Unsubscribe
navigationButtonEventListener.remove();

searchBarUpdated (iOS 11+ only) Copy Chapter

Called whenever the SearchBar of NavigationBar is updated.

class MyComponent extends Component {
  componentDidMount() {
    this.navigationEventListener = Navigation.events().bindComponent(this);
  }

  componentWillUnmount() {
    // Not mandatory
    if (this.navigationEventListener) {
      this.navigationEventListener.remove();
    }
  }

  searchBarUpdated({ text, isFocused }) {}
}

searchBarCancelPressed (iOS 11+ only) Copy Chapter

Called when the cancel button of the SearchBar from NavigationBar is pressed.

class MyComponent extends Component {
  componentDidMount() {
    this.navigationEventListener = Navigation.events().bindComponent(this);
  }

  componentWillUnmount() {
    // Not mandatory
    if (this.navigationEventListener) {
      this.navigationEventListener.remove();
    }
  }

  searchBarCancelPressed() {}
}

previewCompleted (iOS 11.4+ only) Copy Chapter

Called when preview peek is completed.

class MyComponent extends Component {
  componentDidMount() {
    this.navigationEventListener = Navigation.events().bindComponent(this);
  }

  componentWillUnmount() {
    // Not mandatory
    if (this.navigationEventListener) {
      this.navigationEventListener.remove();
    }
  }

  previewCompleted({ previewComponentId }) {}
}

Api Api Modal (`website/docs/api/api-modal.mdx`) Copy Section

id: modal title: Modal sidebar_label: Modal Copy Chapter

`showModal()` Copy Chapter

Show a screen as a modal.

Parameters

Navigation.showModal({
  stack: {
    children: [{
      component: {
        name: 'example.ModalScreen',
        passProps: {
          text: 'stack with one child'
        },
        options: {
          topBar: {
            title: {
              text: 'Modal'
            }
          }
        }
      }
    }]
  }
});

`dismissModal()` Copy Chapter

Dismiss the current modal.

Parameters

Navigation.dismissModal(this.props.componentId);

`dismissAllModals()` Copy Chapter

Dismiss all current modals at the same time.

Parameters

Navigation.dismissAllModals();

Api Api Options (`website/docs/api/api-options.mdx`) Copy Section

id: options-api title: Options Commands sidebar_label: Options commands Copy Chapter

`setDefaultOptions` Copy Chapter

Set default options for all screens. Useful for declaring a consistent style across the app.

Parameters

Example

Navigation.setDefaultOptions({
  bottomTab: {
    textColor: 'black',
    selectedTextColor: 'blue',
  },
});

`mergeOptions` Copy Chapter

Change navigation options of a component or layout.

Parameters

Example

Navigation.mergeOptions('componentId', {
  bottomTabs: {
    visible: false,
  },
});

Api Api Overlay (`website/docs/api/api-overlay.mdx`) Copy Section

id: overlay title: Overlay sidebar_label: Overlay Copy Chapter

`showOverlay()` Copy Chapter

Shows a component as an overlay.

Navigation.showOverlay({
  component: {
    name: 'example.Overlay',
    options: {
      layout: {
            componentBackgroundColor: 'transparent',
          },
      overlay: {
        interceptTouchOutside: true
      }
    }
  }
});

`dismissOverlay()` Copy Chapter

Dismisses an overlay matching the given overlay componentId.

Parameters

Navigation.dismissOverlay(this.props.componentId);

`dismissAllOverlays()` Copy Chapter

Dismisses all overlays.

Navigation.dismissAllOverlays();

Api Api Root (`website/docs/api/api-root.mdx`) Copy Section

id: root title: Root sidebar_label: Root Copy Chapter

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

`setRoot()` Copy Chapter

Used to set the UI of the application. Read more about the root hierarchy level in the docs section.

Parameters

Example

<Tabs
defaultValue='stack'
values={[
{ label: 'With Stack layout', value: 'stack' },
{ label: 'With BottomTabs layout', value: 'bottomTabs' }
]
}>

Navigation.setRoot({
  root: {
    stack: {
      children: [{
        component: {
          name: 'example.FirstTabScreen',
          passProps: {
            text: 'This is tab 1'
          }
        }
      }],
      options: {
        bottomTab: {
          text: 'Tab 1',
          icon: require('../images/one.png'),
          testID: 'FIRST_TAB_BAR_BUTTON'
        }
      }
    }
  }
});

Navigation.setRoot({
  root: {
    bottomTabs: {
      children: [{
        stack: {
          children: [{
            component: {
              name: 'example.FirstTabScreen',
              passProps: {
                text: 'This is tab 1'
              }
            }
          }],
          options: {
            bottomTab: {
              text: 'Tab 1',
              icon: require('../images/one.png'),
              testID: 'FIRST_TAB_BAR_BUTTON'
            }
          }
        }
      },
      {
        component: {
          name: 'navigation.playground.TextScreen',
          passProps: {
            text: 'This is tab 2'
          },
          options: {
            bottomTab: {
              text: 'Tab 2',
              icon: require('../images/two.png'),
              testID: 'SECOND_TAB_BAR_BUTTON'
            }
          }
        }
      }]
    }
  }
});

Api Api SideMenu (`website/docs/api/api-sideMenu.mdx`) Copy Section

id: sideMenu-api title: Side Menu sidebar_label: Side Menu Copy Chapter

This layout allows to implement sidemenus, which can be opened by swiping from one side towards the other side.

{
  left: {
    component: {}
  },
  center: {
    stack: {
      options: {},
      children: [{
        component: {}
      }]
    }
  },
  right: {
    component: {}
  }
}

`center: Layout` Copy Chapter

Center component, contains the main application.

`left?: Layout` Copy Chapter

Contain the left component layout.

`right?: Layout` Copy Chapter

Contain the right component layout.

Api Api Stack (`website/docs/api/api-stack.mdx`) Copy Section

id: stack title: Stack sidebar_label: Stack Copy Chapter

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

`push()` Copy Chapter

Push a screen into the stack and update the display according to the screen options.

Parameters

Example

<Tabs
defaultValue='component'
values={[
{ label: 'Component', value: 'component', },
{ label: 'Update options on push', value: 'push', },
{ label: 'Push other layouts', value: 'otherLayout', },
]
}>

Navigation.push(this.props.componentId, {
  component: {
    name: 'example.PushedScreen'
  }
});

Navigation.push(this.props.componentId, {
  component: {
    name: 'example.PushedScreen',
    options: {
      topBar: {
        title: {
          text: 'Pushed screen title'
        }
      }
    }
  }
});

Navigation.push(this.props.componentId, {
  sideMenu: {
    left: {
      component: {
        name: 'drawerScreen'
      }
    },
    center: {
      component: {
        name: 'centerScreen'
      }
    }
  }
});

`pop()` Copy Chapter

Pop the top screen from the stack.

Parameters

Navigation.pop(this.props.componentId);

`popToRoot()` Copy Chapter

Pop all screens pushed into the stack.

Parameters

Navigation.popToRoot(this.props.componentId);

`popTo()` Copy Chapter

Pop the stack to a given component.

Parameters

Navigation.popTo(componentId);

`setStackRoot()` Copy Chapter

Reset the stack to the given layout (accepts multiple children).

Parameters

Example

<Tabs
defaultValue='single'
values={[
{ label: 'Single child', value: 'single' },
{ label: 'Multiple children', value: 'multiple' }
]
}>

Navigation.setStackRoot(this.props.componentId, {
  component: {
    name: 'example.NewRootScreen'
  }
});

Navigation.setStackRoot(this.props.componentId, [
  {
    component: {
      name: 'NewRootScreen',
    }
  },
  {
    component: {
      name: 'PushedScreen',
    }
  }
]);

Api Layout BottomTabs (`website/docs/api/layout-BottomTabs.mdx`) Copy Section

id: layout-bottomTabs title: Bottom Tabs sidebar_label: Bottom Tabs Copy Chapter

A container view for managing a radio-style selection interface, where a selection determines which child view controller to display.

{
  id: 'BOTTOM_TABS_LAYOUT',
  children: [
    {
      component: {
        id: 'HOME_SCREEN',
        name: 'HomeScreen'
      }
    },
    {
      stack: {
        id: 'PROFILE_TAB',
        children: [
          {
            component: {
              id: 'PROFILE_SCREEN',
              name: 'ProfileScreen'
            }
          }
        ]
      }
    }
  ]
}

`id` Copy Chapter

`children` Copy Chapter

`options` Copy Chapter

Api Layout Component (`website/docs/api/layout-component.mdx`) Copy Section

id: layout-component title: Component sidebar_label: Component Copy Chapter

{
  name: "MyRegisteredComponent";
}

`name` Copy Chapter

`id` Copy Chapter

`options` Copy Chapter

`alignment` Copy Chapter

`waitForRender` Copy Chapter

This option is useful for ensuring that both a child screen pushed into the stack and all of the TopBar components (title, background and buttons) are displayed to the user at the same time.

To enable this option, waitForRender in the relevant screen animation option needs to be enabled as well.

:::caution
This option might introduce delays when pushing screens and should be used with caution.
:::

`passProps` Copy Chapter

Api Layout Layout (`website/docs/api/layout-layout.mdx`) Copy Section

id: layout-layout title: Layout sidebar_label: Layout Copy Chapter

`id` Copy Chapter

`options` Copy Chapter

`children` Copy Chapter

Api Layout SideMenu (`website/docs/api/layout-sideMenu.mdx`) Copy Section

id: layout-sideMenu title: Side Menu sidebar_label: Side Menu Copy Chapter

This layout allows implementing sidemenus, which can be opened by swiping from one side towards the other side.

{
  left: {
    component: {}
  },
  center: {
    stack: {
      options: {},
      children: [{
        component: {}
      }]
    }
  },
  right: {
    component: {}
  }
}

`center` Copy Chapter

`left` Copy Chapter

`right` Copy Chapter

Api Layout SplitView (`website/docs/api/layout-splitView.mdx`) Copy Section

id: layout-splitView title: SplitView sidebar_label: SplitView Copy Chapter

A container view controller implementing a master-detail interface. See UISplitViewController docs.
Currently implemented only in iOS.

{
  id: 'PROFILE_TAB',
  master: {
    component: {
      id: 'MASTER_SCREEN',
      name: 'MasterScreen'
    }
  },
  detail: {
    component: {
      id: 'DETAIL_SCREEN',
      name: 'DetailScreen'
    }
  }
}

`id` Copy Chapter

`master` Copy Chapter

`detail` Copy Chapter

`options` Copy Chapter

Api Layout Stack (`website/docs/api/layout-stack.mdx`) Copy Section

id: layout-stack title: Stack sidebar_label: Stack Copy Chapter

A stack is a container layout promoting a hierarchical navigation. It is used to navigate between screens at consecutive levels of hierarchy, steps in a flow or across an app.

{
  id: 'PROFILE_TAB',
  children: [
    {
      component: {
        id: 'PROFILE_SCREEN',
        name: 'ProfileScreen'
      }
    }
  ]
}

`id` Copy Chapter

`children` Copy Chapter

`options` Copy Chapter

Api Options Animations (`website/docs/api/options-animations.mdx`) Copy Section

id: options-animations title: Animations sidebar_label: Animations Copy Chapter

Api Options BackButton (`website/docs/api/options-backButton.mdx`) Copy Section

id: options-backButton title: Back Button Options sidebar_label: Back Button Copy Chapter

Controls the back button styling.

const options = {
  topBar: {
    backButton: {},
  },
};

`accessibilityLabel` Copy Section

Overrides the text that's read by the screen reader when the user interacts with the back button.

`id` Copy Section

Button id for reference press event.

`color` Copy Section

Change the back button color. This will change the text color as well.

`icon` Copy Section

Change the default back button icon.

`sfSymbol` Copy Section

SF Symbol to show as the back button

`showTitle` Copy Section

Show or hide the text displayed next to the back button.

`displayMode` Copy Section

Set display mode of the back button. Currently works for iOS 14+ only.
See: UINavigationItem.BackButtonDisplayMode

`title` Copy Section

Change the text displayed next to the title. Usually the back button shows the title of the previous screen.

`visible` Copy Section

Hide or show the back button.

`testID` Copy Section

Used to interact with the back button in e2e tests.

`enableMenu` Copy Section

Enables iOS 14 back button menu display.

`popStackOnPress` Copy Section

Controls whether the default back button should pop screen or not.

`hideSharedBackground` Copy Section

Hide the shared Liquid-Glass / Platter background that UIKit draws behind the back button starting with iOS 26. RNN defaults this to true when the back button uses an iconBackground so the system Platter does not double-decorate it. Set to false to keep the system-drawn background.

Api Options Background (`website/docs/api/options-background.mdx`) Copy Section

id: options-background title: Background Options sidebar_label: Background Copy Chapter

Controls the top bar background styling.

const options = {
  topBar: {
    background: {}
  }
};

`color` Copy Section

Set the background color. Ignored if a component is specified.

`component` Copy Section

Set a react component as the background. Useful when you need to show a gradient as background, for instance.

On Android, setting an id to the Component will prevent the component from being recreated each time it's used by a screen. The component will be created once and whenever possible it will be reused.

`clipToBounds` Copy Section

Clip the top bar background to bounds if set to true.

`translucent` Copy Section

Allows the NavBar to be translucent (blurred).

`blur` Copy Section

Enable background blur.

Api Options BottomTab (`website/docs/api/options-bottomTab.mdx`) Copy Section

id: options-bottomTab title: Bottom Tab Options sidebar_label: Bottom Tab Copy Chapter

const options = {
  bottomTab: {},
};

Recommended: Custom bottom tabs guide for React tab items and examples.

`component` Copy Chapter

Render a registered React component as the tab item content (icon + label area).

bottomTab: {
  component: {
    name: 'MyTabItem',
    passProps: { /* optional, merged at creation */ },
  },
}

Requirements: Every tab in the same bottomTabs layout must declare component, or RNN falls back to native rendering for all tabs.

Props delivered to the component: componentId, tabIndex, selected, badge (updated when selection/badge changes).

Ignored when set: text, icon, selectedIcon, sfSymbol, sfSelectedSymbol, iconColor, selectedIconColor, iconWidth, iconHeight, iconInsets, fontFamily, fontWeight, fontSize, selectedFontSize, textColor, selectedTextColor.

Native still owns selection, visibility, drawBehind, animations, and dotIndicator. Pair with bottomTabs.customRow to style the floating row.

Tab press and selection events match native bottom tabs; long press is not available on custom items. See Custom bottom tabs — Events.

`selectTabOnPress` Copy Chapter

`popToRoot` Copy Chapter

Pop to root of stack by tapping on already selected tab.

`badge` Copy Chapter

`badgeColor` Copy Chapter

`animateBadge` Copy Chapter

`disableIconTint` Copy Chapter

`dotIndicator` Copy Chapter

`fontFamily` Copy Chapter

`fontStyle` Copy Chapter

`fontWeight` Copy Chapter

`fontSize` Copy Chapter

`icon` Copy Chapter

`iconWidth` Copy Chapter

The width (in dp) of the icon.

`iconHeight` Copy Chapter

The height (in dp) of the icon.

`iconColor` Copy Chapter

`selectedFontSize` Copy Chapter

`selectedIcon` Copy Chapter

`selectedIconColor` Copy Chapter

`iconInsets` Copy Chapter

`disableSelectedIconTint` Copy Chapter

`disableIconTint` Copy Chapter

`selectedTextColor` Copy Chapter

`testID` Copy Chapter

`accessibilityLabel` Copy Section

Overrides the text that's read by the screen reader when the user interacts with the bottomTab button.

`text` Copy Chapter

`textColor` Copy Chapter

`sfSymbol` Copy Section

Set the SF symbol as icon (will be used primarily).

`sfSelectedSymbol` Copy Section

Set the SF symbol as selected icon (will be used primarily)

DotIndicator Copy Chapter

color?: color

size?: number

visible?: boolean

animate?: boolean

IconInsets Copy Chapter

top?: number

left?: number

right?: number

bottom?: number

Api Options BottomTabs (`website/docs/api/options-bottomTabs.mdx`) Copy Section

id: options-bottomTabs title: Bottom Tabs Options sidebar_label: Bottom Tabs Copy Chapter

Recommended: Read about Bottom Tabs in the Bottom Tabs Guide. For React tab items, see Custom bottom tabs.

const options = {
  bottomTabs: {},
};

`customRow` Copy Chapter

Visual options for the floating row that hosts custom React tab cells. Only applies when every tab uses bottomTab.component.

bottomTabs: {
  customRow: {
    height: 67,
    backgroundEffect: 'glass',
    cornerRadius: 28,
    horizontalMargin: 16,
    bottomMargin: 0,
  },
}

On Android, customRow is forwarded from JS via RNNBottomTabsCustomRowModule (no change to existing BottomTabs layout code). On iOS, options are parsed natively from the layout tree.

BottomTabsCustomRowOptions Copy Section

`height`

Content height of the row in points (iOS) / dp (Android). Excludes safe-area inset.

Default: native tab content height; on iOS 26+ an extra 18pt is added when height is omitted.

Total visible row height = height + safe-area bottom + bottomMargin.

`backgroundColor`

Solid row background. When set, overrides backgroundEffect.

`backgroundEffect`

Default: glass on iOS 26+, blur on older iOS.

`cornerRadius`

Corner radius of the row background.

Default: 28 on iOS 26+, 0 on older iOS / when omitted on Android until configured.

`horizontalMargin`

Horizontal inset from the screen edges.

Default: 16 on iOS 26+, 0 when omitted.

`bottomMargin`

Distance between the row's bottom edge and the safe-area bottom.

Default: 0.

`animate` Copy Chapter

Controls whether toggling visibility states will be animated.

`animateTabSelection` Copy Chapter

Controls wether tab selection is animated or not

`backgroundColor` Copy Chapter

Specify the background color.
On Android - also applicable when translucence is applied, but a semi-transparent color should be used (e.g. rgba(255, 0, 0, 0.25)).

`barStyle` Copy Chapter

Controls whether the BottomTabs use dark (black) or light (default) visual style. Requires translucent: true.

`layoutStyle` Copy Chapter

Control the way the bottom tabs are laid out.

• stretch: Fill the entire width of the screen.
• compact: Occupy the minimum width needed to hold tab buttons. Recommended for usage in conjunction with drawBehind: true.

`currentTabId` Copy Chapter

Select a tab by the id (componentId) of a child contained in it. See Selecting tabs programmatically for a detailed explanation.

`currentTabIndex` Copy Chapter

`drawBehind` Copy Chapter

`elevation` Copy Chapter

`cornerRadius` Copy Chapter

Specify a corner-radius in order to apply round corners to the tabs container.
Mainly suitable when used in conjunction with layoutStyle: 'compact'

`bottomMargin` Copy Chapter

Bottom-margin to set in order to enable a "hover" effect.
Works best when used in conjunction with layoutStyle: 'compact' and drawBehind: true.

`hideShadow` Copy Chapter

`hideOnScroll` Copy Chapter

Hides the BottomTabs on scroll to increase the amount of content visible to the user.
The options requires that the scrollable view will be the root view of the screen and that it specifies nestedScrollEnabled: true.

`preferLargeIcons` Copy Chapter

`tabsAttachMode` Copy Chapter

`testID` Copy Chapter

`titleDisplayMode` Copy Chapter

`translucent` Copy Chapter

A Boolean value that indicates whether the BottomTabs should be translucent (and background-blurred).
For this option to function properly the screen needs to be drawn behind the BottomTabs; Make sure the list component you're using (FlatList for example) is the root component in the screen and not SafeAreaView. When SafeAreView is the root component it shifts the content above the BottomTabs and the translucent effect isn't visible.

Note: On Android, the option is experimental and should be enabled using a native feature-toggle called TAB_BAR_TRANSLUCENCE (pass it to your NavigationApplication class' c'tor).

`blurRadius` Copy Chapter

Set a custom radius to be used in the blur effect. Higher is blurrier, but also more CPU-intensive.
Note: The blurring is performed following a bitmap downscale of x4.0, so ultimately the actual radius is (4*blurRadius).

`visible` Copy Chapter

Api Options Button (`website/docs/api/options-button.mdx`) Copy Section

id: options-button title: Button Options sidebar_label: Button Copy Chapter

const options = {
  topBar: {
    leftButtons: [
      {
        id: 'id',
        text: 'Button',
      },
    ],
  },
};

`allCaps` Copy Section

This option will set whether characters are all capitalized or not.

`fontSize` Copy Section

If the button has text, this option is used to set font size in DP.

`fontFamily` Copy Section

`fontStyle` Copy Section

`fontWeight` Copy Section

`id` Copy Section

Buttons are identified by their id property. When a button is clicked, a buttonPress event is emitted to js, containing the id of the clicked button.

`icon` Copy Section

Button icon. If the button is pushed to the overflow menu, the button text is used instead.

`sfSymbol` Copy Section

SF Symbol to show as the back button

`text` Copy Section

Button text. Ignored if an icon is specified, unless the button is displayed in the overflow menu.

`showAsAction` Copy Section

• ifRoom - Only add button to the TopBar if there is room for it, otherwise add it to the overflow menu.
• never - Never place this button in the TopBar. Instead, list the button in the overflow menu.
• always - Always place this button in the app bar.

`component` Copy Section

Set a react component as this button's view which will be displayed instead of the regular view.

`iconInsets` Copy Section

IconInsets are applied to the icon to translate its original position on the screen.

`systemItem` Copy Section

System icon; ignored if an icon is specified. For more information, see apple's guidelines.

`iconBackground` Copy Section

iconBackground is applied to the icon's background.

`hideSharedBackground` Copy Section

Hide the shared Liquid-Glass / Platter background that UIKit draws behind every bar button item starting with iOS 26. RNN defaults this to true for buttons that paint their own chrome (custom react component views and icons with iconBackground) so the system Platter does not double-decorate them. Set to false to keep the system-drawn background.

Api Options Fab (`website/docs/api/options-fab.mdx`) Copy Section

id: options-fab title: Fab sidebar_label: Fab Copy Chapter

Controls the FAB button styling on Android.

const options = {
  fab: {
    id: 'id',
    icon: require('path-to-fab-icon'),
    backgroundColor: 'coral',
    actions: [
      {
        id: 'id2',
        icon: require('path-to-fab-icon-2),
      }
    ]
  },
};

`id` Copy Section

Button id for reference press event.

:::info Note
This option is mandatory when you are initiating the FAB button. However you do not need to pass in id when updating the Fab button options with Navigation.mergeOptions.
:::

`icon` Copy Section

Change the default back button icon.

`iconColor` Copy Section

Change the icon color of the FAB button.

`backgroundColor` Copy Section

Change the background color of the FAB button.

`clickColor` Copy Section

Change the on-clicked background color of the FAB button.

`rippleColor` Copy Section

Change the ripple color of the FAB button.

`visible` Copy Section

Show or hide the FAB button.

`alignHorizontally` Copy Section

Set the horizontal position of the FAB button on the screen.

`hideOnScroll` Copy Section

Hide the FAB button on scroll.

`size` Copy Section

Set the size of the FAB button.

Api Options HardwareBackButton (`website/docs/api/options-hardwareBackButton.mdx`) Copy Section

id: options-hardwareBackButton title: Hardware Back Button Options sidebar_label: Hardware Back Button Copy Chapter

Controls Android hardware back button.

const options = {
  hardwareBackButton: {},
};

`dismissModalOnPress` Copy Section

Controls whether the hardware back button should dismiss modal or not.

`popStackOnPress` Copy Section

Controls whether the hardware back button should pop stacks or not.

`bottomTabsOnPress` Copy Section

Controls hardware back button bottom tab selection behaviour,
first will jump to first tab,
previous will do reverse selection,
exit (Default) will just exit the bottom tabs.

Api Options IconBackground (`website/docs/api/options-iconBackground.mdx`) Copy Section

id: options-iconBackground title: iconBackground Options sidebar_label: iconBackground Copy Chapter

`color` Copy Section

Set the background color.

`width` Copy Section

Set the background width.

`height` Copy Section

Set the background height.

`cornerRadius` Copy Section

Set the background cornerRadius.

Api Options IconInsets (`website/docs/api/options-iconInsets.mdx`) Copy Section

id: options-iconInsets title: IconInsets Options sidebar_label: IconInsets Copy Chapter

`top` Copy Section

Configure top inset

`bottom` Copy Section

Configure bottom inset

`left` Copy Section

Configure left inset

`right` Copy Section

Configure right inset

Api Options ImageResource (`website/docs/api/options-imageResource.mdx`) Copy Section

id: options-imageResource title: Image Resource sidebar_label: Image Resource Copy Chapter

`ImageResource` Copy Chapter

const options = {
  topBar: {
    leftButtons: [
        icon: require('./backButton.png')
    ]
  },
};

The following icon types are available:

`ImageSystemSource` Copy Chapter

`system` Copy Section

You can use platform specific system icons for iOS only.

Example:

const options = {
  topBar: {
    leftButtons: [
        icon: {
            system: 'calendar',
            fallback: require('./calendar.png')
        }
    ]
  },
};

`fallback` Copy Section

`FallbackSource` Copy Chapter

For iOS, SF Symbols is available only for iOS 13 and later. For iOS 12 and earlier you should use a fallback icon.

`ImageRequireSource` Copy Section

`string` Copy Section

Api Options LargeTitle (`website/docs/api/options-largeTitle.mdx`) Copy Section

id: options-largeTitle title: Large Title Options sidebar_label: Large Title Copy Chapter

Controls the top bar large title on iOS, available on iOS 11 and above.

const options = {
  topBar: {
    largeTitle: {},
  },
};

`visible` Copy Section

Controls whether the large title is visible or not.

`fontSize` Copy Section

Set the title font size. On Android this value is in sp.

`color` Copy Section

Large title text color.

`fontFamily` Copy Section

Set the large title FontFamily.

`fontStyle` Copy Section

`fontWeight` Copy Section

Api Options Layout (`website/docs/api/options-layout.mdx`) Copy Section

id: options-layout title: Layout Options sidebar_label: Layout Copy Chapter

const options = {
  layout: {},
};

`fitSystemWindows` Copy Section

`backgroundColor` Copy Section

Set the screen background color.

`componentBackgroundColor` Copy Section

Set background color only for components. On Android, using this option instead of backgroundColor helps reduce overdraw.

`orientation` Copy Section

Set the allowed orientations.

`topMargin` Copy Section

Set the layout top margin.

`direction` Copy Section

Set language direction, only works with DefaultOptions. locale is an Android specific option which sets the direction according to the device locale.

`autoHideHomeIndicator` Copy Section

Controls the application's preferred home indicator auto-hiding.

Api Options Migration (`website/docs/api/options-migration.mdx`) Copy Section

Common Options

navBarTextColor Copy Chapter

Title text color

topBar: {
  title: {
    color: 'red'
  }
}

navBarTextFontSize Copy Chapter

Title font size

topBar: {
  title: {
    fontSize: 18
  }
}

navBarTextFontFamily Copy Chapter

Title font

topBar: {
  title: {
    fontFamily: 'Helvetica'
  }
}

navBarBackgroundColor Copy Chapter

TopBar background color

topBar: {
  background: {
    color: 'red'
  }
}

navBarCustomView Copy Chapter

Use a react view as the TopBar's background or use a React view instead of the textual title.

topBar: {
  background: {
    component: {
      name: 'example.CustomTopBarBackground'
    }
  },
  title: {
    component: {
      name: 'example.CustomTopBarTitle'
    }
  }
}

navBarClipToBounds Copy Chapter

Restrict the navbar background color to the navbar, and do not flow behind the status bar.

topBar: {
  background: {
    component: {
      name: 'example.CustomTopBarBackground',
      clipToBounds: true
    }
  },
}

navBarComponentAlignment Copy Chapter

Align the React view used as the title

topBar: {
  title: {
    component: {
      name: 'example.CustomTopBarTitle',
      alignment: 'center' | 'fill'
    }
  }
}

navBarCustomViewInitialProps Copy Chapter

Initial props passed to the React component

topBar: {
  background: {
    component: {
      name: 'example.CustomTopBarBackground',
      passProps: {}
    }
  },
  title: {
    component: {
      name: 'example.CustomTopBarTitle',
      passProps: {}
    }
  }
}

navBarButtonColor Copy Chapter

TopBar button color

topBar: {
  rightButtons: [
    {
      color: 'red'
    }
  ],
  leftButtons: [
    {
      color: 'red'
    }
  ],
  backButton: {
    color: 'red'
  }
}

navBarHidden Copy Chapter

TopBar visibility. When setting visible: false, you probably want to set drawBehind: true as well. Use animate: false to toggle visibility without animation.

topBar: {
  visible: false
}

navBarTransparent Copy Chapter

Transparent TopBar. Set drawBehind: true to draw the screen behind the transparent TopBar.

topBar: {
  background: {
    color: 'transparent'
  }
}

drawUnderNavBar Copy Chapter

Draw the screen behind the TopBar, Useful when the TopBar is toggled or transparent

topBar: {
  drawBehind: true
}

drawUnderTabBar Copy Chapter

Draw the screen behind the BottomTabs, Useful when toggling BottomTabs or when the BottomTabs are translucent.

bottomTabs: {
  drawBehind: true
}

tabBarHidden Copy Chapter

BottomTabs visibility.

bottomTabs: {
  visible: false
}

The BottomTab's visibility can be toggled only on Android using mergeOptions:

Navigation.mergeOptions(this.props.componentId, {
  bottomTabs: {
    visible: false
  }
});

On iOS, BottomTab visibility can be changed only when pushing screens. This means that if you'd like to hide BottomTabs when pushing a screen, You'll need to set the property to false in the options passed to the push command or via the static options(passProps) {} api.

statusBarHidden Copy Chapter

StatusBar visibility. For android, also set drawBehind: true.

statusBar: {
  visible: false
}

statusBarTextColorScheme Copy Chapter

Theme of text and icons displayed in the StatusBar

statusBar: {
  style: 'light' | 'dark'
}

navBarSubtitleColor Copy Chapter

Subtitle color

topBar: {
  subtitle: {
    color: 'red'
  }
}

navBarSubtitleFontFamily Copy Chapter

Subtitle font

topBar: {
  subtitle: {
    fontFamily: 'Helvetica'
  }
}

navBarSubtitleFontSize Copy Chapter

Subtitle font size

topBar: {
  subtitle: {
    fontSize: 14
  }
}

screenBackgroundColor Copy Chapter

Screen color, visible before the actual React view is rendered

layout: {
  backgroundColor: 'red'
}

orientation Copy Chapter

layout: {
  orientation: ['portrait', 'landscape'] // An array of supported orientations
}

disabledButtonColor Copy Chapter

Button color when enabled: false is used

topBar: {
  rightButtons: [
    {
      disabledColor: 'grey'
    }
  ]
}

navBarButtonFontSize Copy Chapter

Button font size

topBar: {
  rightButtons: [
    {
      fontSize: 13
    }
  ],
  leftButtons: [
    {
      fontSize: 13
    }
  ]
}

navBarLeftButtonFontSize Copy Chapter

Left button font size

{
  topBar: {
    leftButtons: [
      {
        fontSize: 13
      }
    ]
  }
}

navBarLeftButtonColor Copy Chapter

Left button color

{
  topBar: {
    leftButtons: [
      {
        color: 'red'
      }
    ]
  }
}

navBarLeftButtonFontWeight Copy Chapter

Left button font weight

{
  topBar: {
    leftButtons: [
      {
        weight: '300'
      }
    ]
  }
}

navBarRightButtonFontSize Copy Chapter

Right button font size

topBar: {
  leftButtons: [
    {
      fontSize: 13
    }
  ]
}

navBarRightButtonColor Copy Chapter

Right button color

topBar: {
  rightButtons: [
    {
      color: 'red'
    }
  ]
}

navBarRightButtonFontWeight Copy Chapter

Right button font weight

topBar: {
  rightButtons: [
    {
      weight: '400'
    }
  ]
}

modalPresentationStyle Copy Chapter

Controls the behavior of screens displayed modally.

Options supported on iOS Copy Section

• overCurrentContext - Content is displayed over the previous screen. Useful for transparent modals
• formSheet - Content is centered in the screen
• pageSheet -Content partially covers the underlying content
• overFullScreen - Content covers the screen, without detaching previous content.
• fullScreen - Content covers the screen, previous content is detached.
• popover - Content is displayed in a popover view.

More information on the different styles for iOS can be found on https://developer.apple.com/documentation/uikit/uimodalpresentationstyle

Options supported on Android Copy Section

• overCurrentContext - Content is displayed over the previous screen. Useful for transparent modals
• none - Previous content is detached when the Modal's show animation ends

{
  modalPresentationStyle: 'overCurrentContext'
}

navBarButtonFontFamily Copy Chapter

Button font family

topBar: {
  rightButtons: [
    {
      fontFamily: 'Helvetica'
    }
  ]
}

iOS only

navBarHideOnScroll Copy Chapter

Hide TopBar when list is scrolled

topBar: {
  hideOnScroll: true
}

navBarTranslucent Copy Chapter

Translucent TopBar, Setting drawBehind: true is required for this property to work as expected.

topBar: {
  drawBehind: true,
  background: {
    translucent: true
  }
}

navBarNoBorder Copy Chapter

Remove TopBar border (hair line)

topBar: {
  noBorder: true
}

navBarBlur Copy Chapter

Blur the area behind the TopBar, Setting drawBehind: true and topBar background transparent: true is required for this property to work as expected.

topBar: {
  drawBehind: true,
  background: {
    blur: true,
    transparent: true
  }
}

rootBackgroundImageName Copy Chapter

• iOS: name of image in Images.xcassets
• Android: name of drawable

{
  rootBackgroundImage: require('rootBackground.png')
}

screenBackgroundImageName Copy Chapter

name of image in Images.xcassets

{
  backgroundImage: require('background.png')
}

statusBarHideWithNavBar Copy Chapter

Hide the StatusBar if the TopBar is also hidden

statusBar: {
  hideWithTopBar: true
}

statusBarBlur Copy Chapter

Blur the area behind the StatusBar

statusBar: {
  blur: true
}

statusBarAnimate Copy Chapter

Animate between style changes of the StatusBar

statusBar: {
  animate: true
}

disabledBackGesture Copy Chapter

Disable the back (swipe) gesture used to pop screens

{
  popGesture: false
}

largeTitle Copy Chapter

Use iOS 11 large title

topBar: {
    largeTitle: {
      visible: true,
      fontSize: 30,
      color: 'red',
      fontFamily: 'Helvetica'
    }
  }

Android Options

topBarElevationShadowEnabled Copy Chapter

TopBar elevation in dp. Set this value to 0 to disable the TopBar's shadow.

topBar: {
  elevation: 0
}

navBarTitleTextCentered Copy Chapter

Title alignment

topBar: {
  title: {
    alignment: 'center'|'fill'
  }
}

statusBarColor Copy Chapter

StatusBar color

statusBar: {
  backgroundColor: 'red'
}

navigationBarColor Copy Chapter

NavigationBar color

navigationBar: {
  backgroundColor: 'red'
}

drawUnderStatusBar Copy Chapter

Draw content behind the StatusBar

statusBar: {
  drawBehind: true
}

navBarHeight Copy Chapter

TopBar height in dp

topBar: {
  height: 70
}

navBarTopPadding Copy Chapter

Content top margin

layout: {
    topMargin: 26
  }

topTabsHeight Copy Chapter

TopTabs height

topTabs: {
  height: 70
}

topBarBorderColor Copy Chapter

TopBar border color

topBar: {
  borderColor: 'red'
}

topBarBorderWidth Copy Chapter

TopBar border height

topBar: {
  borderHeight: 1.3
}

Unsupported options

• disabledSimultaneousGesture
• statusBarTextColorSchemeSingleScreen
• navBarButtonFontWeight
• topBarShadowColor
• topBarShadowOpacity
• topBarShadowOffset
• topBarShadowRadius
• preferredContentSize
• navBarSubTitleTextCentered
• collapsingToolBarImage
• collapsingToolBarCollapsedColor
• navBarTextFontBold

Api Options Modal (`website/docs/api/options-modal.mdx`) Copy Section

id: options-modal title: Modal Options sidebar_label: Modal Copy Chapter

const options = {
  swipeToDismiss
};

`swipeToDismiss` Copy Chapter

Control wether this modal should be dismiss using swipe gesture when the modalPresentationStyle is pageSheet

Api Options NavigationBar (`website/docs/api/options-navigationBar.mdx`) Copy Section

id: options-navigationBar title: Navigation Bar Options sidebar_label: Navigation Bar Copy Chapter

import useBaseUrl from '@docusaurus/useBaseUrl';

The Navigation Bar is the area at the bottom of the screen containing Android's three navigation buttons: Back, Home and Recents.

:::info Edge-to-Edge
Starting with Android 15 (API 35), the system enforces edge-to-edge by default. React Native Navigation supports this via a theme opt-in. See the Edge-to-Edge guide for setup instructions. Navigation bar options below work in both edge-to-edge and non-edge-to-edge modes.
:::

An example of a dark navigation bar:

const options = {
  navigationBar: {}
};

`visible` Copy Section

Set the navigation bar visibility.

`backgroundColor` Copy Section

Set the navigation bar color. When a light background color is used, the color of the navigation bar icons will adapt to a dark color.

`drawBehind` Copy Section

Draw screen content behind the system navigation bar while keeping it visible (gesture pill / 3-button bar remain on screen). Use with edge-to-edge enabled in your activity. With backgroundColor: 'transparent', content shows through the nav bar area; with an opaque color, RNN paints a scrim overlay without reserving bottom layout inset.

Api Options Overlay (`website/docs/api/options-overlay.mdx`) Copy Section

id: options-overlay title: Overlay sidebar_label: Overlay Copy Chapter

Controls overlay options

const options = {
  overlay: {

  }
}

`interceptTouchOutside` Copy Section

Controls whether touch events outside the bounds of the overlay are to be handled by content behind the overlay. When set to true, touch events will not pass through to the underlying content.

`handleKeyboardEvents` Copy Section

Overlays on iOS don't handle keyboard events by default. If your Overlay contains a TextInput component, you'll want to enable this option so that TextInput responds to keyboard events.

Api Options Preview (`website/docs/api/options-preview.mdx`) Copy Section

id: options-preview title: Preview (iOS) sidebar_label: Preview (iOS) Copy Chapter

Api Options Root (`website/docs/api/options-root.mdx`) Copy Section

id: options-root title: The options object sidebar_label: Options object Copy Chapter

const options = {
  bottomTab,
  bottomTabs,
  topBar,
  layout,
  sideMenu,
  overlay,
  modal,
  preview,
  navigationBar,
  scrollEdgeEffect,
};

`bottomTab` Copy Chapter

Controls the bottom tab icon, font, color, and more.

`bottomTabs` Copy Chapter

Controls the bottom tabs container.

`topBar` Copy Chapter

Controls the Stack top bar styling.

`statusBar` Copy Chapter

Controls the system status bar styling.

`layout` Copy Chapter

`sideMenu` Copy Chapter

`overlay` Copy Chapter

`animations` Copy Chapter

`modal` Copy Chapter

`preview` Copy Chapter

`splitView` Copy Chapter

`fab` Copy Chapter

`modalPresentationStyle` Copy Chapter

Configure the presentation style of the modal.

Styles supported on both platforms

• overCurrentContext - Display the modal and do not remove previous content when the show animation ends.
• none - default system presentation style

Styles supported only on iOS

• fullScreen - The view covers the underlying content completely.
• pageSheet - partially cover the underlying content.
• formSheet - display content centered in the screen.
• overFullScreen - display the modal in full screen mode and do not remove previous content when the show animation ends.
• popOver - Center content on screen and dim the content behind it.

The default presentation style is different on each platform.

`modalTransitionStyle` Copy Chapter

Configure the transition style of the modal.

`popGesture` Copy Chapter

Enable or disable swipe back to pop gesture.

`navigationButtonEventOnSwipeBack` Copy Chapter

Enable NavigationButtonPressed event sending on Swipe-back on pushed VC.

`backgroundImage` Copy Chapter

Background image of the screen.

`rootBackgroundImage` Copy Chapter

Background image for the Navigation View.

`blurOnUnmount` Copy Chapter

Enable or disable automaticall blur of the focused input, dismissing keyboard on unmount.

`scrollEdgeEffect` Copy Chapter

Show / hide or change the style of the iOS 26 scroll edge effect on every UIScrollView contained in the screen.

`navigationBar` Copy Chapter

Enable or disable automaticall blur of the focused input, dismissing keyboard on unmount.

Api Options ScrollEdgeAppearance (`website/docs/api/options-scrollEdgeAppearance.mdx`) Copy Section

id: options-scrollEdgeAppearance title: Scroll Edge Appearance Options sidebar_label: Scroll Edge Appearance Copy Chapter

Controls the top bar background styling.

const options = {
  topBar: {
    scrollEdgeAppearance: {
      background: {},
      active: true,
    },
  },
};

`active` Copy Section

Since this might be considered as a breaking change (meaning that previous configs might behave different), you'll need to
pass active true/false to activate this option.

`color` Copy Section

Set the background color.

`translucent` Copy Section

Allows the Scroll Edge Appearance to be translucent (blurred).

`borderColor` Copy Section

Change the topBar border color.

`noBorder` Copy Section

Disables border at the bottom of the TopBar.

Api Options ScrollEdgeEffect (`website/docs/api/options-scrollEdgeEffect.mdx`) Copy Section

id: options-scrollEdgeEffect title: Scroll Edge Effect Options sidebar_label: Scroll Edge Effect Copy Chapter

Controls the iOS 26+ UIScrollEdgeEffect (Liquid Glass fade) shown at the edges of scroll views when content scrolls under bars.

Credits: Contributed by @manuhook (PR #8281).

const options = {
  scrollEdgeEffect: {
    hidden: true,
  },
};

`hidden` Copy Section

Hide the scroll edge effect.

`style` Copy Section

Set the scroll edge effect style.

`top` / `bottom` / `left` / `right` Copy Section

Per-edge override. Values fall back to the global hidden / style. Per-edge values take precedence.

Examples Copy Chapter

Hide all edges:

MyScreen.options = {
  scrollEdgeEffect: { hidden: true },
};

Top visible, bottom hidden:

MyScreen.options = {
  scrollEdgeEffect: {
    top: { hidden: false },
    bottom: { hidden: true },
  },
};

Dynamic update:

Navigation.mergeOptions(componentId, {
  scrollEdgeEffect: { bottom: { hidden: true } },
});

Api Options SideMenu (`website/docs/api/options-sideMenu.mdx`) Copy Section

id: options-sideMenu title: Side Menu Options sidebar_label: Side Menu Copy Chapter

const options = {
  sideMenu: {
    left: {},
    right: {},
    openGestureMode: 'entireScreen',
  },
};

`left` Copy Section

Configure the left side menu.

`right` Copy Section

Configure the right side menu.

`openGestureMode` Copy Section

Configure how a user is allowed to open a drawer using gestures.

Api Options SideMenuSide (`website/docs/api/options-sideMenuSide.mdx`) Copy Section

id: options-sideMenuSide title: Side Menu Side Options sidebar_label: Side Menu Side Copy Chapter

const options = {
  sideMenu: {
    left: {
      visible: false,
      enabled: true
    }
  }
};

`visible` Copy Section

Show or hide the side menu.

`enabled` Copy Section

Enable or disable the side menu.

`width` Copy Section

Set the width of the side menu.

`height` Copy Section

Set the height of the side menu.

Api Options SplitView (`website/docs/api/options-splitView.mdx`) Copy Section

id: options-splitView title: SplitView Options sidebar_label: SplitView Copy Chapter

`displayMode` Copy Section

Master view display mode.

`primaryEdge` Copy Section

Master view side. Leading is left. Trailing is right.

`minWidth` Copy Section

Set the minimum width of master view.

`maxWidth` Copy Section

Set the maximum width of master view.

`primaryBackgroundStyle` Copy Section

Set background style of sidebar. Currently works for Mac Catalyst apps only.
See: Optimizing Your iPad App for Mac

Api Options Stack (`website/docs/api/options-stack.mdx`) Copy Section

id: options-stack title: Top Bar Options sidebar_label: Top Bar Copy Chapter

TopBar Copy Chapter

const options = {
  topBar: {
    animate: true,
    title: {},
    subtitle: {},
    backButton: {},
    background: {},
  },
};

`visible` Copy Section

Determines if TopBar is visible or not.

`animate` Copy Section

Determines if changing the TopBar visibility will be animated or not.

`animateLeftButtons` Copy Section

Determines if changing the left buttons will be animated.

`animateRightButtons` Copy Section

Determines if changing the right buttons will be animated.

`title` Copy Section

Controls the top bar title.

`subtitle` Copy Section

Controls the top bar subtitle.

`backButton` Copy Section

Controls the top bar back button.

`background` Copy Section

Controls the top bar background.

`scrollEdgeAppearance` Copy Section

Controls the appearance settings when the scrollable content reaches the matching edge of the navigation bar.

`barStyle` Copy Section

Control the TopBar blur style. Requires translucent: true.

`height` Copy Section

Set TopBar height, in dp units, on Android only. For iOS use largeTitle see Options.

`borderColor` Copy Section

Change the topBar border color.

`borderHeight` Copy Section

Set the border height of the navbar in dp.

`drawBehind` Copy Section

Controls if child should be drawn behind the TopBar or below it.

`elevation` Copy Section

Set the elevation of the TopBar in dp. This option changes how the shadow under the TopBar looks. Setting this value to 0 will remove the shadow completely.

`hideOnScroll` Copy Section

Hide the TopBar when a scrolling layout is scrolled.

:::warning Deprecation warning
This option is currently deprecated and will be removed in a future release. Please use the OptionsSearchBar option instead.
:::

`hideNavBarOnFocusSearchBar` Copy Section

Indicates whether the navigation bar should be hidden when searching. True by default.

`leftButtons` Copy Section

An array of buttons to be displayed at the right-side of the TopBar. Button layout is from left to right. See the Buttons section for more details.

:::info Android support
Android currently only supports a single left button and does not support custom left Buttons.
:::

`leftButtonColor` Copy Section

Default color for left buttons.

`noBorder` Copy Section

Disables border at the bottom of the TopBar.
:::important
For disabling the border completely, you also need to disable scrollEdgeAppearance.noBorder
:::

`rightButtons` Copy Section

An array of buttons to be displayed at the right side of the TopBar. Button layout is from right to left. See the Buttons section for more details.

`rightButtonColor` Copy Section

Default color for the right button.

`searchBar` Copy Section

Controls the SearchBar.

:::warning Deprecation warning
This option is currently deprecated and will be removed in a future release. Please use the OptionsSearchBar option instead.
:::

`searchBarHiddenWhenScrolling` Copy Section

Hides the UISearchBar when scrolling.

:::warning Deprecation warning
This option is currently deprecated and will be removed in a future release. Please use the OptionsSearchBar option instead.
:::

`searchBarPlaceholder` Copy Section

The placeholder value in the UISearchBar.

:::warning Deprecation warning
This option is currently deprecated and will be removed in a future release. Please use the OptionsSearchBar option instead.
:::

`searchBarBackgroundColor` Copy Section

The background color of the UISearchBar's TextField.

:::warning Deprecation warning
This option is currently deprecated and will be removed in a future release. Please use the OptionsSearchBar option instead.
:::

`searchBarTintColor` Copy Section

The tint color of the UISearchBar. Affects text selection color, as well as "Cancel" button color.

Api Options StatusBar (`website/docs/api/options-statusBar.mdx`) Copy Section

id: options-statusBar title: Status Bar Options sidebar_label: Status Bar Copy Chapter

const options = {
  statusBar: {},
};

`visible` Copy Section

Set the status bar visibility.

`style` Copy Section

Set the text color of the status bar.

`backgroundColor` Copy Section

Set the background color of the status bar.

`drawBehind` Copy Section

Draw screen behind the status bar.

`translucent` Copy Section

Set the status bar to be translucent.

`animate` Copy Section

Animate StatusBar style changes.

`blur` Copy Section

Blur content beneath the StatusBar.

`hideWithTopBar` Copy Section

Automatically hide the StatusBar when the TopBar hides.

Api Options Subtitle (`website/docs/api/options-subtitle.mdx`) Copy Section

id: options-subtitle title: Subtitle Options sidebar_label: Subtitle Copy Chapter

Controls the top bar subtitle.

const options = {
  topBar: {
    subtitle: {},
  },
};

`text` Copy Section

Subtitle text.

`fontSize` Copy Section

Subtitle fontSize. On Android this value is sp.

`color` Copy Section

Subtitle color.

`fontFamily` Copy Section

Subtitle FontFamily.

`fontStyle` Copy Section

`fontWeight` Copy Section

`alignment` Copy Section

fill will make the subtitle stretch and consume all available space in the TopBar while center will center the subtitle in the middle of the TopBar.

`testID` Copy Section

Used to interact with the TopBar in e2e tests.

Api Options Title (`website/docs/api/options-title.mdx`) Copy Section

id: options-title title: Title Options sidebar_label: Title Copy Chapter

Controls the top bar title.

const options = {
  topBar: {
    title: {},
  },
};

`text` Copy Section

Set the title for the TopBar.

`fontSize` Copy Section

Set the title font size. On Android this value is in sp.

`color` Copy Section

Set the title color.

`fontFamily` Copy Section

Set the title font family.

`fontStyle` Copy Section

`fontWeight` Copy Section

`alignment` Copy Section

fill will make the title stretch and consume all available space in the TopBar while center will center the title in the middle of the TopBar.

:::info defaults
center is the default option on iOS while fill is the default for Android.
:::

`component` Copy Section

Set a react component as the title. If this option is specified then text is ignored.

`topMargin` Copy Section

Change to TopBar's top margin.

`visible` Copy Section

Determines whether the TopBar is visible or not.

Api TopBar SearchBar (`website/docs/api/topBar-searchBar.mdx`) Copy Section

id: topBar-searchBar title: SearchBar sidebar_label: Layout Copy Chapter

`visible` Copy Chapter

`focus` Copy Chapter

`hideOnScroll` Copy Chapter

`hideTopBarOnFocus` Copy Chapter

`obscuresBackgroundDuringPresentation` Copy Chapter

`backgroundColor` Copy Chapter

`tintColor` Copy Chapter

`searchBarPlaceholder` Copy Chapter

`cancelText` Copy Chapter

`placement` Copy Chapter

Docs Community Libraries (`website/docs/docs/community-libraries.mdx`) Copy Section

id: community-libraries title: Community libraries sidebar_label: Community libraries Copy Chapter

React Native Navigation has an active community with a bunch of support libraries.

Utilities Copy Chapter

React Native Navigation Hooks :
A set of React hooks for React Native Navigation.

React Native Navigation Register Screens :
Utility function to register array of screens instead of calling Navigation.registerComponent multiple times.

Extensions Copy Chapter

React Native Navigation Drawer Extension :
Drawer API built on top of React Native Navigation for iOS and Android.

React Native Navigation Search Bar :
React Native Elements search bar with collapsible header built for React Native Navigation.

React Native Navigation Bottom Sheet Extension :
A performant customizable bottom sheet component built on top of React Native Navigation.

Docs Docs Installing (`website/docs/docs/docs-Installing.mdx`) Copy Section

id: installing title: Installation sidebar_label: Installation Copy Chapter

Requirements Copy Chapter

• node ≥ 18.18
• react-native ≥ 0.77
• new architecture enabled

npm or yarn Copy Chapter

npm:

npm install --save react-native-navigation

yarn:

yarn add react-native-navigation

Installing with `npx rnn-link` (automatic installation) Copy Chapter

You can benefit from autolinking for some of the necessary installation steps. But unlike most other libraries, react-native-navigation requires you to make a few changes to native files.

We've simplified the process through a set of scripts. So to make all the necessary changes automatically, in your project's root folder run:

npx rnn-link

Make sure to commit the changes introduced by the rnn-link script.

The automatic linking is optimized for new applications created via the npx @react-native-community/cli@latest init command. If you are migrating from a version of react-native-navigation older than v7, it's recommended to check the steps manually after the script runs.

In iOS, from React-native 0.79 onwards the rnn-link will make the necessary changes only to the AppDelegate.swift file. The Objective-C version of the AppDelegate will need to be changed manually (see below).

If one of the steps failed or you can't run (or are not comfortable with) the automatic scripts, you'll need to complete the relevant steps in the manual installation steps below, for both platforms.

CocoaPods Copy Section

After the the automatic scripts completed successfully, run pod install:

pod install --project-directory=ios

Update index.js file Copy Section

index.js is typically used as an entry point into the app. It's first parsed and executed by the JS engine, therefore we'll want to show our UI from there.

The following diff demonstrates changes needed to be made to index.js, initialized by react-native init.

+import { Navigation } from "react-native-navigation";
-import {AppRegistry} from 'react-native';
import App from "./App";
-import {name as appName} from './app.json';

-AppRegistry.registerComponent(appName, () => App);
+Navigation.registerComponent('com.myApp.WelcomeScreen', () => App);

+Navigation.events().registerAppLaunchedListener(() => {
+   Navigation.setRoot({
+     root: {
+       stack: {
+         children: [
+           {
+             component: {
+               name: 'com.myApp.WelcomeScreen'
+             }
+           }
+         ]
+       }
+     }
+  });
+});

Finish Copy Section

If you followed the steps successfully up to this point, then rebuild your application and you are good to go:

react-native run-ios
react-native run-android

:::tip
This is a good moment to build your application in both platforms, validate that everything is working properly and commit your changes. If you're coming from a fresh npx @react-native-community/cli@latest init project, then you should be seeing the Welcome screen as usual, but under the hood your application is using react-native-navigation!
::::

Manual Installation Copy Chapter

If installation with npx rnn-link did not work, follow the manual installation steps below.

iOS Copy Section

Make sure your Xcode is updated. We recommend editing .h, .mm and .swift files in Xcode as the IDE will usually point out common errors.

Installation with CocoaPods

cd ios && pod install

Native Installation

Choose your implementation language: Depending on whether your project uses Swift or Objective-C, follow the appropriate section below. Most new React Native projects use Swift by default.

React-Native 0.77 - 0.78: Copy Section

For Swift projects

In Xcode, you will need to update this file: AppDelegate.swift

import UIKit
import React
- import React_RCTAppDelegate
+ import ReactNativeNavigation
import ReactAppDependencyProvider

@main
- class AppDelegate: RCTAppDelegate {
+ class AppDelegate: RNNAppDelegate {
...

For Objective-C projects

In Xcode, you will need to edit this file: AppDelegate.h. Its content should look like this:

#import <UIKit/UIKit.h>
- #import <RCTAppDelegate.h>
+ #import "RNNAppDelegate.h"

- @interface AppDelegate : RCTAppDelegate
+ @interface AppDelegate : RNNAppDelegate

@end

React-Native 0.79: Copy Section

For Swift projects

-import React_RCTAppDelegate
+import ReactNativeNavigation

-class AppDelegate: UIResponder, UIApplicationDelegate {
+class AppDelegate: RNNAppDelegate {

-func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
+override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
+self.reactNativeDelegate = ReactNativeDelegate()
+super.application(application, didFinishLaunchingWithOptions: launchOptions)

-let delegate = ReactNativeDelegate()
-let factory = RCTReactNativeFactory(delegate: delegate)
-delegate.dependencyProvider = RCTAppDependencyProvider()

-reactNativeDelegate = delegate
-reactNativeFactory = factory

-window = UIWindow(frame: UIScreen.main.bounds)

-factory.startReactNative(
-  withModuleName: "RN79",
-  in: window,
-  launchOptions: launchOptions
-)

For Objective-C projects

In Xcode, you will need to edit this file: AppDelegate.h. Its content should look like this:

-@interface AppDelegate: UIResponder, UIApplicationDelegate
+@interface AppDelegate : RNNAppDelegate

-@property (nonatomic, strong) UIWindow *window;
-@property (nonatomic, strong) ReactNativeDelegate *reactNativeDelegate;
-@property (nonatomic, strong) RCTReactNativeFactory *reactNativeFactory;

AppDelegate.m

-  ReactNativeDelegate *delegate = [[ReactNativeDelegate alloc] init];
-  RCTReactNativeFactory *factory = [[RCTReactNativeFactory alloc] initWithDelegate:delegate];
-  delegate.dependencyProvider = [[RCTAppDependencyProvider alloc] init];

-  self.reactNativeDelegate = delegate;
-  self.reactNativeFactory = factory;
-  self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];

-  [factory startReactNativeWithModuleName:@"RN79"
-                                      in:self.window
-                            launchOptions:launchOptions];
+  self.reactNativeDelegate = [ReactNativeDelegate new];
+  [super application:application didFinishLaunchingWithOptions:launchOptions];

Firebase integration on React-Native 0.79: Copy Section

For Firebase integration with static frameworks the following change needs to be added to your podfile:

podfile

linkage = ENV['USE_FRAMEWORKS']
if linkage != nil
  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
  use_frameworks! :linkage => linkage.to_sym
end

+ static_frameworks = [
+  'FirebaseCore',
+  'FirebaseCoreExtension',
+  'GoogleUtilities',
+  'FirebaseCoreInternal',
+  'FirebaseInstallations',
+  'GoogleDataTransport',
+  'FirebaseFirestoreInternal',
+  'FirebaseMessagingInternal',
+  'FirebaseAuth',
+ ]

+ pre_install do |installer|
+  installer.pod_targets.each do |pod|
+    if static_frameworks.include?(pod.name)
+      puts "Configuring #{pod.name} as static framework"
+      def pod.build_type
+        Pod::BuildType.new(:linkage => :static, :packaging => :framework)
+      end
+    end
+  end
+ end

target <ProjectName> do
  config = use_native_modules!

+ $RNFirebaseAsStaticFramework = true

+  pod 'FirebaseAuthInterop', :modular_headers => true
+  pod 'FirebaseAppCheckInterop', :modular_headers => true
+  pod 'RecaptchaInterop', :modular_headers => true
...

Android Copy Section

Make sure your Android Studio installation is up to date. We recommend editing gradle and kotlin files in Android Studio as the IDE will suggest fixes and point out errors, this way you avoid most common pitfalls.

1. Update `android/build.gradle`:

buildscript {
    ext {
        kotlinVersion = "2.0.21"
+        RNNKotlinVersion = kotlinVersion
        compileSdkVersion = 35
        buildToolsVersion = "35.0.0"
        minSdkVersion = 24
        targetSdkVersion = 34
        ndkVersion = "27.1.12297006"
    }
  repositories {
        google()
        mavenCentral()
  }
  dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
        classpath("com.facebook.react:react-native-gradle-plugin")
        classpath 'com.android.tools.build:gradle'
  }
}

allprojects {
  repositories {
   google()
    maven {
      // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
      url "$rootDir/../node_modules/react-native/android"
    }
  }
}

2. Update `MainActivity.kt`

-import com.facebook.react.ReactActivity
+import com.reactnativenavigation.NavigationActivity

-class MainActivity : ReactActivity() {
-    override fun getMainComponentName(): String {
-        return "yourproject"
-    }
-}
+class MainActivity : NavigationActivity()

If you have any react-native related methods, you can safely delete them.

3. Update `MainApplication.kt`

This file is located in android/app/src/main/java/com/<yourproject>/MainApplication.java.

/* Detailed source-code truncated for AI context efficiency. */

App root Copy Section

Now that you're done, don't forget to update the index.js file, as shown above.

Troubleshooting Copy Chapter

Build app with gradle command Copy Section

prefered solution - The RNN flavor you would like to build is specified in app/build.gradle. Therefore in order to compile only that flavor, instead of building your entire project using ./gradlew assembleDebug, you should instruct gradle to build the app module: ./gradlew app:assembleDebug. The easiest way is to add a package.json command to build and install your debug Android APK .

"scripts": {
  // ...
  "android": "cd ./android && ./gradlew app:assembleDebug && ./gradlew installDebug"
}

Now run npm run android to build your application

Force the same support library version across all dependencies Copy Section

Some of your dependencies might require a different version of one of Google's support library packages. This results in compilation errors similar to this:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:preDebugBuild'.
> Android dependency 'com.android.support:design' has different version for the compile (25.4.0) and runtime (26.1.0) classpath. You should manually set the same version via DependencyResolution

To resolve these conflicts, add the following to your app/build.gradle:

android {
    ...
}

configurations.all {
    resolutionStrategy.eachDependency { DependencyResolveDetails details ->
        def requested = details.requested
        if (requested.group == 'com.android.support' && requested.name != 'multidex') {
            details.useVersion "${rootProject.ext.supportLibVersion}"
        }
    }
}

dependencies {
    ...
    implementation 'com.android.support:design:25.4.0'
    implementation "com.android.support:appcompat-v7:${rootProject.ext.supportLibVersion}"
}

Docs Docs Advanced Navigation (`website/docs/docs/docs-advanced-navigation.mdx`) Copy Section

id: advanced-navigation title: Advanced navigation sidebar_label: Advanced navigation Copy Chapter

import useBaseUrl from '@docusaurus/useBaseUrl';

Tab navigation Copy Chapter

As mobile applications become bigger and more complex, they usually end up containing multiple primary high-level destinations, which are logically independent from one another. The BottomTabs layout is often used when an app contains three to five top-level destinations which should be accessible from anywhere in the app.

Lets return to the example code from the previous section (Basic navigation) and see how we can convert it to a tab-based application. We'll use the BottomTabs layout to display tabs at the bottom of the screen. Similarly to Stack layout, The BottomTabs layout also contains a children property where each child will be displayed in a tab.

Lets change our code to the following and reload the app.

/* Detailed source-code truncated for AI context efficiency. */

Now our app has two tabs at the bottom of the screen and our users can easily navigate between them.

Replacing the root Copy Chapter

Up until now, we've discussed how to navigate within the same layout structure. We'll now learn how to replace the entire layout structure to display a new Root. A real life example for this use case would be, for instance, if you need to switch from a login screen to the app's main root. Replacing the root fits this use case since we'd like to discard the previous root (login root) entirely when switching to the main root.

To demonstrate this, we'll make the following changes to our code:

1. Add a login screen with a login button.
2. When the button is clicked, we will switch to the main root.
3. Replace our current root with the login screen. We'll also extract both roots to variables to improve code readability.

/* Detailed source-code truncated for AI context efficiency. */

Conditional roots Copy Chapter

Now that our initial root is the Login root, we're facing a new problem - how do we show the Login root only to users that are not logged in? Since our initial root is determined in the registerAppLaunchedListener callback, we'll check if a user is logged in there and set the appropriate root accordingly.

Navigation.events().registerAppLaunchedListener(async () => {
  Navigation.setRoot(isLoggedIn() ? mainRoot : loginRoot);
});

function isLoggedIn() {
  // TODO: your business logic goes here
}

Docs Docs App Launch (`website/docs/docs/docs-app-launch.mdx`) Copy Section

id: app-launch title: Launching the app sidebar_label: Launching the app Copy Chapter

When your app is launched for the first time, the bundle is parsed and executed. At this point you need to display your UI. To do so, listen to the appLaunched event and call Navigation.setRoot when that event is received.

Navigation.events().registerAppLaunchedListener(() => {
  // Each time the event is received you should call Navigation.setRoot
});

:::important
Register the app launched listener as soon as possible - this should be one of the first lines in your index.js file.
:::

If you're observing a "white screen" or a hanging splash screen after relaunching your app, it probably means Navigation.setRoot isn't called as soon as the app is launched. Perhaps the listener was registered too late.

Difference between the platforms Copy Chapter

When your app is launched, RN makes sure JS context (which is what enables you to execute JavaScript code) is running. There are quite a few differences between iOS and Android in this regard.

iOS Copy Section

Whenever an app is put into the background, the app process can potentially be destroyed by the system. If this destruction takes place, the JS context will be destroyed alongside with the app process.

Android Copy Section

An Android application is typically bound to two contexts:

1. Application context - bound to the app process
2. Activity context - bound to app UI

React's JS Context is executed on and bound to the Application context. This means that even when the Activity context (and thus the UI) is destroyed, React's JS Context remains active until the Application (and your process) are destroyed by the system.

:::caution
Because of this, when your app returns to foreground, JS Context might still exist on Android, even when the Activity and UI contexts have been destroyed - meaning you might not need to initialise all of your app logic; instead, you'll only need to call Navigation.setRoot to repopulate the UI context. This circumstance can easily be determined by setting a flag on your app's first appLaunched event, and checking the value of that flag on subsequent appLaunched events -- if the flag is true in your appLaunched callback, you need to call Navigation.setRoot to repopulate the UI.
:::

Docs Docs Basic Navigation (`website/docs/docs/docs-basic-navigation.mdx`) Copy Section

id: basic-navigation title: Basic navigation sidebar_label: Basic navigation Copy Chapter

import useBaseUrl from '@docusaurus/useBaseUrl';

Generally, any mobile app consists of various destinations which display some content to the user. And in vast majority of cases using an app means navigating between these destinations. React-native-navigation provides ways for you to layout your content on user screen in a logical and performant manner.

React Native Navigation's stack layout lets you push screens, and also navigate back to previous screens. Screens pushed into the stack hide the previous screen in the stack, making the user focus on a single screen at a time. Let's look at a stack layout that provides basic navigation for an app.

Creating a stack Copy Chapter

// In index.js of a new project
import React from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import { Navigation } from 'react-native-navigation';

const HomeScreen = (props) => {
  return (
    <View style={styles.root}>
      <Text>Home Screen</Text>
    </View>
  );
};
Navigation.registerComponent('Home', () => HomeScreen);

Navigation.events().registerAppLaunchedListener(async () => {
  Navigation.setRoot({
    root: {
      stack: {
        children: [
          {
            component: {
              name: 'Home'
            }
          }
        ]
      }
    }
  });
});

const styles = StyleSheet.create({
  root: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    backgroundColor: 'whitesmoke'
  }
});

Running this code will render a screen with an empty TopBar and your HomeScreen component (shown below). The TopBar is part of the stack layout, we'll work on configuring it later.

Specifying options Copy Chapter

You can specify options of each layout (Stack, component pushed into a stack, etc.) to configure various parameters like the TopBar title or color. Lets spice things up by changing the TopBar color and while we're at it, also move the title to the TopBar.

Lets change the Home screen declaration to the following and reload the app to see the changes.

const HomeScreen = (props) => {
  return (
    <View style={styles.root}>
      <Text>Hello React Native Navigation 👋</Text>
    </View>
  );
};
HomeScreen.options = {
  topBar: {
    title: {
      text: 'Home',
      color: 'white'
    },
    background: {
      color: '#4d089a'
    }
  }
}

Our app should now look like this:

Navigating in a stack Copy Chapter

In the previous section we created a stack and initialized it with a single child. We'll now learn how to add another child to the stack. From now on, we'll call the action of adding children to the stack 'push', and removing children - 'pop'.

In order to push another screen to the stack, we will add a button to the home screen and call Navigation.push. The 'push' command accepts two parameters, the first is the id used to indicate into which stack to push the screen and the second is the screen we're pushing. After pushing a screen, a back button is added automatically to the TopBar so the users can navigate easily back to the previous screen.

You can read more about the stack layout here or dive right into the API here.

:::info componentId
Each React component registered with Navigation.registerComponent is assigned a unique componentId by Navigation. This unique id is used with Navigation commands (like the push command) to indicate into which stack we'd like to push. In this case, by using the componentId of the Home screen, we are telling Navigation to push into the stack containing the Home screen.
:::

Navigation.push(props.componentId, {
  component: {
    name: 'Settings', // Push the screen registered with the 'Settings' key
    options: { // Optional options object to configure the screen
      topBar: {
        title: {
          text: 'Settings' // Set the TopBar title of the new Screen
        }
      }
    }
  }
});

Lets change our code to the following snippet below and reload the app. Now our Home should contain a button which when pressed, pushes a new screen into the stack. We've successfully navigated to a new screen! 👏

/* Detailed source-code truncated for AI context efficiency. */

App theme Copy Chapter

Our app is growing and already contains two screens. This introduces a new problem - while the home screen has a nice purple TopBar, our settings screen seems pretty dull as it still uses the default system look and feel.

Currently, our style declaration applies only to the Home screen, so lets apply it to all of our screens by using Navigation.setDefaultOptions.

Navigation.setDefaultOptions({
  statusBar: {
    backgroundColor: '#4d089a'
  },
  topBar: {
    title: {
      color: 'white'
    },
    backButton: {
      color: 'white'
    },
    background: {
      color: '#4d089a'
    }
  }
});

We need to add this snippet before registering the registerAppLaunchedListener. This way we ensure our theme is applied when our root is set. Our code should now look like this:

/* Detailed source-code truncated for AI context efficiency. */