@chain1/navigation-helpers

React Navigation utility functions for imperative navigation in React Native applications.

Features

• ✅ Imperative navigation without navigation prop
• ✅ Type-safe navigation helpers
• ✅ Stack navigation utilities (push, pop, replace)
• ✅ Reset navigation stack
• ✅ Nested navigation support
• ✅ Safe navigation with error handling
• ✅ Current route information
• ✅ Delayed navigation helpers

Installation

npm install @chain1/navigation-helpers

Peer Dependencies

npm install @react-navigation/native @react-navigation/stack

Setup

1. Configure Navigation Container

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { navigationRef } from '@chain1/navigation-helpers';

function App() {
  return (
    <NavigationContainer ref={navigationRef}>
      {/* Your navigation structure */}
    </NavigationContainer>
  );
}

Usage

Basic Navigation

import { navigate, goBack } from '@chain1/navigation-helpers';

// Navigate to a screen
navigate('Home');

// Navigate with params
navigate('Profile', { userId: '123' });

// Go back
goBack();

Stack Operations

import { push, pop, replace, popToTop } from '@chain1/navigation-helpers';

// Push new screen
push('Details', { id: '456' });

// Pop screens
pop(); // Pop 1 screen
pop(3); // Pop 3 screens

// Replace current screen
replace('Login');

// Pop to top of stack
popToTop();

Reset Navigation

import { reset, resetToScreen } from '@chain1/navigation-helpers';

// Reset to specific screen
resetToScreen('Home');

// Reset with multiple screens
reset([
  { name: 'Home' },
  { name: 'Profile', params: { userId: '123' } },
]);

Route Information

import { getCurrentRoute, getCurrentParams, canGoBack } from '@chain1/navigation-helpers';

// Get current route name
const routeName = getCurrentRoute(); // "Home"

// Get current route params
const params = getCurrentParams(); // { userId: '123' }

// Check if can go back
if (canGoBack()) {
  goBack();
}

Advanced Features

import { navigateWithDelay, navigateNested, safeNavigate } from '@chain1/navigation-helpers';

// Navigate with delay
navigateWithDelay('Details', { id: '789' }, 500);

// Nested navigation
navigateNested([
  { name: 'MainTabs' },
  { name: 'Profile', params: { userId: '123' } },
]);

// Safe navigation with error handling
safeNavigate(() => {
  navigate('SomeScreen');
});

API Reference

Navigation Functions

navigate(name: string, params?: object): void

Navigate to a screen.

navigate('Home');
navigate('Profile', { userId: '123' });

goBack(): void

Go back to the previous screen.

goBack();

push(name: string, params?: object): void

Push a new screen onto the stack.

push('Details', { id: '456' });

pop(count?: number): void

Pop N screens from the stack (default: 1).

pop(); // Pop 1 screen
pop(3); // Pop 3 screens

replace(name: string, params?: object): void

Replace the current screen.

replace('Login');

popToTop(): void

Pop to the top of the stack.

popToTop();

reset(routes: Route[]): void

Reset the navigation stack.

reset([
  { name: 'Splash' },
  { name: 'Home' },
]);

resetToScreen(name: string, params?: object): void

Reset to a single screen.

resetToScreen('Home', { reload: true });

Information Functions

getCurrentRoute(): string | undefined

Get the current route name.

const routeName = getCurrentRoute();

getCurrentParams(): object | undefined

Get the current route params.

const params = getCurrentParams();

canGoBack(): boolean

Check if navigation can go back.

if (canGoBack()) {
  goBack();
}

Utility Functions

navigateWithDelay(name: string, params?: object, delay?: number): void

Navigate with a delay (default: 300ms).

navigateWithDelay('Details', { id: '123' }, 500);

goBackWithDelay(delay?: number): void

Go back with a delay (default: 300ms).

goBackWithDelay(500);

navigateNested(screens: Route[]): void

Navigate to nested screens.

navigateNested([
  { name: 'TabNavigator' },
  { name: 'HomeTab' },
  { name: 'Details', params: { id: '123' } },
]);

safeNavigate(fn: () => void): void

Execute navigation with error handling.

safeNavigate(() => {
  navigate('SomeScreen');
});

Examples

Authentication Flow

import { resetToScreen, navigate } from '@chain1/navigation-helpers';

// After login
function handleLogin() {
  // Reset to Home, clearing auth stack
  resetToScreen('Home');
}

// After logout
function handleLogout() {
  // Reset to Login
  resetToScreen('Login');
}

Deep Linking

import { navigateNested } from '@chain1/navigation-helpers';

function handleDeepLink(url: string) {
  if (url.includes('/profile/')) {
    const userId = extractUserId(url);
    navigateNested([
      { name: 'MainTabs' },
      { name: 'Profile', params: { userId } },
    ]);
  }
}

Conditional Navigation

import { canGoBack, goBack, navigate } from '@chain1/navigation-helpers';

function handleBack() {
  if (canGoBack()) {
    goBack();
  } else {
    navigate('Home'); // Go to Home if can't go back
  }
}

Modal Navigation

import { navigate, goBack } from '@chain1/navigation-helpers';

// Open modal
function openModal() {
  navigate('ModalScreen', { data: { /* ... */ } });
}

// Close modal
function closeModal() {
  goBack();
}

TypeScript Support

Full TypeScript support with type definitions.

import { navigate, NavigationHelpers } from '@chain1/navigation-helpers';

// Type-safe navigation
navigate('Home');
navigate('Profile', { userId: string });

Best Practices

1. Always setup navigationRef in NavigationContainer
2. Use resetToScreen for auth flows
3. Check canGoBack() before calling goBack()
4. Use safeNavigate for error-prone navigation
5. Prefer navigate over push for simple navigation

Common Issues

"Navigation not ready" warning

Wait for NavigationContainer to be ready:

import { NavigationContainer } from '@react-navigation/native';

<NavigationContainer
  ref={navigationRef}
  onReady={() => {
    console.log('Navigation ready');
  }}
>
  {/* ... */}
</NavigationContainer>

Navigation not working

Ensure navigationRef is properly set:

import { navigationRef } from '@chain1/navigation-helpers';

<NavigationContainer ref={navigationRef}>

License

MIT