native-navigation

name	native-navigation
description	Use when adding or reviewing UI navigation so internal routes preserve normal SPA behavior plus Cmd/Ctrl-click and middle-click new-tab semantics.
scope	dev

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