Native Navigation

Rule

Pure navigation must render a real React Router <Link> for same-SPA routes,
a native <a href> for external/public or explicit new-tab destinations, or a
shadcn Button asChild wrapper around one. Do not use a button whose only job
is to call navigate(), window.open(), or window.location.

Why

Browser modifier-click, middle-click, keyboard activation, accessibility, and
normal client-side routing come from real links. Imperative JavaScript
navigation hides the destination and blocks those browser semantics.

How

import { Link } from "react-router";

<Link to={`/items/${item.id}`}>...</Link>

<Button asChild>
  <Link to="/settings">Settings</Link>
</Button>

<a href={previewUrl} target="_blank" rel="noopener noreferrer">
  Preview
</a>

• Use Link for same-SPA internal routes.
• Use <a> when the URL is external, crosses an app/public boundary, is an
  auth or sign-in destination, or intentionally opens in a new tab.
• Preserve query strings and hashes in to or href.
• For cards with nested actions, link only the non-interactive card region or
  use a transparent Link overlay; never nest links or buttons.
• If selection mode changes click behavior, prevent default only for an
  unmodified primary click and preserve modified clicks.

Keep imperative navigation for post-mutation redirects, OAuth and popup flows,
downloads, media/blob URLs, playback, keyboard shortcuts, and stateful tabs.

Review

Search for onClick={() => navigate, window.open, window.location,
onAuxClick, and buttons whose only purpose is routing. For each candidate,
confirm whether it is pure navigation or a stateful workflow before changing
it.

Verify the rendered DOM exposes an href, then test normal click, Cmd/Ctrl-click,
middle-click, keyboard Enter, and nested controls where applicable. Run oxfmt
and focused app tests or typechecks for the touched package.

Related Skills

• client-side-routing
• frontend-design
• shadcn-ui