The useNavigation hook provides a unified navigation API that works across different routing frameworks (Next.js, React Router, etc.) through platform adapters.

​
Import

import { useNavigation } from '@snipextt/wacht';

​
Usage

import { useNavigation } from '@snipextt/wacht';

function NavigationExample() {
  const { navigate, navigateToSignIn, navigateToSignUp } = useNavigation();

  return (
    <div>
      <button onClick={() => navigate('/dashboard')}>
        Go to Dashboard
      </button>
      
      <button onClick={() => navigateToSignIn()}>
        Sign In
      </button>
      
      <button onClick={() => navigateToSignUp()}>
        Sign Up
      </button>
    </div>
  );
}

​
Methods

Navigates to a specified path using the platform’s router.
​
to
string
required
The path to navigate to
​
options
NavigateOptions
Navigation options (platform-specific)
const { navigate } = useNavigation();

// Basic navigation
navigate('/dashboard');

// With options
navigate('/profile', { replace: true });
Navigates to the configured sign-in page with optional redirect.
​
redirectUri
string
URL to redirect to after successful sign-in
const { navigateToSignIn } = useNavigation();

// Navigate to sign-in
navigateToSignIn();

// With custom redirect
navigateToSignIn('https://myapp.com/protected');
Navigates to the configured sign-up page with optional redirect.
​
redirectUri
string
URL to redirect to after successful sign-up
const { navigateToSignUp } = useNavigation();

// Navigate to sign-up
navigateToSignUp();

// With custom redirect
navigateToSignUp('https://myapp.com/onboarding');

​
Platform Adapters

The navigation hook automatically uses the appropriate adapter based on your setup:

​
Next.js

// Automatically uses Next.js router
import { useNavigation } from '@snipextt/wacht';

function NextComponent() {
  const { navigate } = useNavigation();
  
  // Uses Next.js router under the hood
  navigate('/about');
}

​
React Router

// Automatically uses React Router
import { useNavigation } from '@snipextt/wacht';

function ReactRouterComponent() {
  const { navigate } = useNavigation();
  
  // Uses React Router navigate function
  navigate('/about');
}

​
Fallback (No Router)

If no platform adapter is available, falls back to window.location.href: 
// Falls back to window.location
navigate('/about'); // Sets window.location.href = '/about'

​
Examples

​
Protected Route Navigation

function ProtectedLink({ children, to }) {
  const { navigate, navigateToSignIn } = useNavigation();
  const { session } = useSession();

  const handleClick = () => {
    if (session) {
      navigate(to);
    } else {
      // Redirect to sign-in with return URL
      navigateToSignIn(window.location.origin + to);
    }
  };

  return (
    <button onClick={handleClick}>
      {children}
    </button>
  );
}

function NavigationWithState() {
  const { navigate } = useNavigation();
  const currentPath = window.location.pathname;

  const navigateWithReturn = (path) => {
    // Save current location
    sessionStorage.setItem('returnTo', currentPath);
    navigate(path);
  };

  const navigateBack = () => {
    const returnTo = sessionStorage.getItem('returnTo');
    if (returnTo) {
      navigate(returnTo);
      sessionStorage.removeItem('returnTo');
    } else {
      navigate('/');
    }
  };

  return (
    <div>
      <button onClick={() => navigateWithReturn('/settings')}>
        Settings
      </button>
      <button onClick={navigateBack}>
        Back
      </button>
    </div>
  );
}

​
Conditional Navigation

function ConditionalNavigation() {
  const { navigate, navigateToSignIn, navigateToSignUp } = useNavigation();
  const { session } = useSession();
  const { activeOrganization } = useActiveOrganization();

  const handleDashboardClick = () => {
    if (!session) {
      navigateToSignIn();
    } else if (!activeOrganization) {
      navigate('/create-organization');
    } else {
      navigate('/dashboard');
    }
  };

  return (
    <button onClick={handleDashboardClick}>
      Go to Dashboard
    </button>
  );
}

​
Development Mode Navigation

function DevelopmentNavigation() {
  const { navigate } = useNavigation();
  const { deployment } = useDeployment();

  const navigateWithDevSession = (path) => {
    if (deployment.mode === 'staging') {
      // In staging mode, dev session is handled automatically
      navigate(path);
    } else {
      navigate(path);
    }
  };

  return (
    <nav>
      <button onClick={() => navigateWithDevSession('/debug')}>
        Debug Panel
      </button>
    </nav>
  );
}
The options parameter supports platform-specific navigation options:

​
Next.js Options

interface NavigateOptions {
  shallow?: boolean;
  locale?: string;
  scroll?: boolean;
}

​
React Router Options

interface NavigateOptions {
  replace?: boolean;
  state?: any;
  relative?: 'route' | 'path';
}

​
Notes

  • The hook automatically detects and uses the appropriate platform adapter
  • In staging mode, development session parameters are handled automatically
  • Sign-in/sign-up navigation includes proper redirect URI encoding
  • Falls back to window.location.href when no router is available
  • Navigation methods are synchronous but may trigger asynchronous routing
  • The deployment configuration determines the sign-in/sign-up URLs