Skip to main content

​
Router

The router provides client-side navigation capabilities in COSMOS RSC applications.

​
useRouter

A React hook that returns the router instance for programmatic navigation. 
'use client';

import { useRouter } from '../../core/client/exports.js';

function MyComponent() {
  const router = useRouter();
  
  return (
    <button onClick={() => router.push('/about')}>
      Go to About
    </button>
  );
}

​
Return Value

The useRouter hook returns a router object with the following methods:
​
push
function
Navigates to a new URL using the push history action.Signature: (url: string) => voidParameters:
  • url - The destination URL path
Uses the browser’s Navigation API to perform the navigation with history management.

​
Error Handling

The hook throws an error if called outside of a router context: 
Error: Router was not mounted
Ensure your component is rendered within the COSMOS RSC application context.

​
RouterContext

The underlying React context that provides the router instance. Most applications should use the useRouter hook instead of accessing this context directly. 
'use client';

import { use } from 'react';
import { RouterContext } from '../../core/client/components/router-context.js';

function MyComponent() {
  const router = use(RouterContext);
  // ...
}
COSMOS RSC’s router is built on top of the browser’s Navigation API, which provides:
  • Programmatic navigation with router.push()
  • Back/forward navigation support
  • Navigation type detection (push, replace, traverse)
  • Navigation transition types for animations
When navigating, COSMOS RSC automatically adds transition types that can be used with the NavigationTransition component:
  • navigation-push - New page navigation
  • navigation-replace - Replacing current page
  • navigation-forward - Forward browser navigation
  • navigation-back - Back browser navigation
  • navigation-traverse - Generic back/forward navigation

​
Browser Compatibility

The router requires the Navigation API, which is available in:
  • Chrome/Edge 102+
  • Safari 16.4+
  • Firefox (behind flag)
If the Navigation API is not available, navigation will fall back to standard link behavior.

​
Examples

​
Basic Navigation

'use client';

import { useRouter } from '../../core/client/exports.js';

function Navigation() {
  const router = useRouter();
  
  return (
    <nav>
      <button onClick={() => router.push('/')}>
        Home
      </button>
      <button onClick={() => router.push('/about')}>
        About
      </button>
      <button onClick={() => router.push('/contact')}>
        Contact
      </button>
    </nav>
  );
}

​
Conditional Navigation

'use client';

import { useRouter } from '../../core/client/exports.js';

function LoginButton({ isAuthenticated }) {
  const router = useRouter();
  
  const handleClick = () => {
    if (isAuthenticated) {
      router.push('/dashboard');
    } else {
      router.push('/login');
    }
  };
  
  return <button onClick={handleClick}>Continue</button>;
}

'use client';

import { useState } from 'react';
import { useRouter } from '../../core/client/exports.js';

function SearchForm() {
  const router = useRouter();
  const [query, setQuery] = useState('');
  
  const handleSubmit = (e) => {
    e.preventDefault();
    router.push(`/search?q=${encodeURIComponent(query)}`);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <button type="submit">Search</button>
    </form>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us