Navigation: Link & useNavigate

Lesson 5 — typed routing between your mobile screens

Your capstone tree has screens. Now make them link to each other. TanStack Router's navigation API is the payoff for all that file-based structure: because routes are generated from files, every to and every params value is type-checked at compile time. A typo in a path is a red squiggle, not a 404.

The <Link> Component

Primary navigation tool. Renders a real <a> tag with a valid href, so cmd/ctrl-click, middle-click, and "open in new tab" all work for free.

import { Link } from '@tanstack/react-router'

// routes/_app/(tabs)/feed/$postId/index.tsx
export default function PostScreen() {
  return (
    <Link to="/profile/u/$username" params={{ username: 'ana' }}>
      View @ana's profile
    </Link>
  )
}

Type-Safe Params

Because the file is named $username, the generated types know this route needs a username param. The shape of params is derived from the path:

Forget a param -> compile error. Add a phantom param -> compile error. The link is impossible to write wrong.

useNavigate — imperative navigation

For side-effect navigations: after a form submit, after an async action resolves, after a timeout. Don't reach for it for anything the user clicks — <Link> is better there (it provides href, accessibility, cmd-click).

import { useNavigate } from '@tanstack/react-router'

function NewPostButton() {
  // pass `from` here for max type-safety
  const navigate = useNavigate({ from: '/feed' })

  const handleSubmit = async (e) => {
    e.preventDefault()
    const res = await fetch('/api/posts', { method: 'POST', ... })
    const { id: postId } = await res.json()
    navigate({ to: '/feed/$postId', params: { postId } })
  }

  return <form onSubmit={handleSubmit}>...</form>
}

The other two flavors (for completeness)

• <Navigate to="..."> — renders nothing, immediately navigates. Useful in render branches (e.g. redirect when auth missing).
• router.navigate(...) — the most powerful; available anywhere you have the router instance, not just inside components.

None of these replace server-side redirects. For pre-mount redirects, do them on the server.

Navigation Options

Both <Link> and navigate() accept these modifiers (from the NavigateOptions interface):

For mobile apps, replace is common — after login, you don't want "back" returning to the login screen.

Relative Paths: "." and ".."

Like a filesystem. From /posts/$postId:

<Link to=".">Reload current route (re-run loaders)</Link>
<Link to="..">Up to parent (/posts)</Link>
<Link from="/posts" to=".">Same as above, explicit</Link>

"." = same route. ".." = one route up the tree. Useful for "back to list" buttons and loader re-runs.

Active Link Styling

For tab bars and nav menus. The link tracks whether its to matches the current URL:

<Link
  to="/feed"
  activeProps={{ className: 'tab-active' }}
  inactiveProps={{ className: 'tab-inactive' }}
>
  Feed
</Link>

The rendered <a> also gets data-status="active" when matched — useful if you prefer CSS attribute selectors over prop merging. This is exactly how you'd build the bottom tab bar's highlighted state.

Next.js → TanStack Quick Map

The big shift: Next.js uses interpolated strings (href="/posts/42"); TanStack uses typed route templates + params object. No more string-concatenating your way into 404s.

Practice Exercise

You're in routes/_app/(tabs)/feed/$postId/index.tsx (the post detail screen). Build:

1. A link to the post author's profile at /profile/u/$username (param value: "ana")
2. A "Back to feed" link using a relative path
3. An imperative navigation to /feed/$postId with a new postId after a fake delete+create flow

Sketch the three pieces mentally, then reveal.

import { Link, useNavigate } from '@tanstack/react-router'

export default function PostScreen() {
  const navigate = useNavigate({ from: '/feed/$postId' })

  const handleRecreate = async () => {
    const { id: newId } = await fetch('/api/posts', { method: 'POST' }).then(r => r.json())
    navigate({ to: '/feed/$postId', params: { postId: newId } })
  }

  return (
    <>
      {/* 1. Typed link to profile */}
      <Link to="/profile/u/$username" params={{ username: 'ana' }}>
        View @ana
      </Link>

      {/* 2. Relative back to feed list */}
      <Link to="..">Back to feed</Link>

      {/* 3. Imperative nav after async action */}
      <button onClick={handleRecreate}>Recreate post</button>
    </>
  )
}

Quick Quiz

Primary source: TanStack Router — Navigation (the <Link> component, useNavigate, and NavigateOptions sections). Read after the quiz to deepen.