Navigation

After routes are defined, use Retend’s navigation APIs to change routes without a full browser reload.

Using Links

Use <Link> for declarative navigation. It renders an HTML <a> element and intercepts clicks to update the URL and rendered route.

Because it uses an <a> element, it retains browser link behavior, including accessibility semantics, search engine discoverability, and opening links in a new tab.

import { Link } from 'retend/router';

export function NavigationMenu() {
  return (
    <nav class="main-nav">
      <Link href="/">Home</Link>
      <Link href="/about">About Us</Link>
      <Link href="/contact">Contact</Link>
    </nav>
  );
}

You can pass standard HTML attributes like class, id, or aria-label directly to the <Link> component:

<Link
  href="/signup"
  class="btn btn-primary"
  aria-label="Sign up for an account"
>
  Get Started
</Link>

Replacing History

By default, clicking a <Link> adds an entry to browser history, so the Back action returns to the previous route.

Use the replace prop to replace the current history entry. This can prevent the previous route, such as a login page after authentication, from being restored by Back:

<Link href="/dashboard" replace>
  Go to Dashboard
</Link>

Navigating from Code

Use programmatic navigation when an operation, such as form submission or payment completion, should change the route.

Call useRouter() to access the router and then call router.navigate().

import { useRouter } from 'retend/router';
import { Cell } from 'retend';

export function LoginForm() {
  const router = useRouter();
  const isSubmitting = Cell.source(false);

  const handleSubmit = async () => {
    isSubmitting.set(true);

    try {
      await performLogin();
      // After login is successful, automatically navigate to the dashboard
      await router.navigate('/dashboard');
    } catch (error) {
      console.error('Login failed', error);
    } finally {
      isSubmitting.set(false);
    }
  };

  return (
    <form onSubmit--prevent={handleSubmit}>
      {/* ... form fields ... */}
      <button type="submit" disabled={isSubmitting}>
        Log In
      </button>
    </form>
  );
}

Use router.replace('/login') to replace the current browser history entry instead of adding one.

Both router.navigate() and router.replace() return Promises. Await them when code must run after the route transition completes.