• Name: Link
• Purpose: High-level navigation link component that automatically gets router from context
• When to use: For creating navigation links in components inside RouterProvider

import { Link } from "@real-router/react";
// or
import { Link } from "@real-router/preact";
// or
import { Link } from "@real-router/solid";
// or
import { Link } from "@real-router/vue";
// or
import { Link } from "@real-router/svelte";

// Angular (directive, not component)
import { RealLink } from "@real-router/angular";
// Used as: <a realLink routeName="home">Home</a>

function Navigation() {
  return (
    <nav>
      <Link routeName="home">Home</Link>
      <Link routeName="users">Users</Link>
      <Link routeName="users.profile" routeParams={{ id: "123" }}>
        Profile
      </Link>
    </nav>
  );
}

Note: Link gets router automatically from RouterProvider context. All navigation props including routeOptions are supported directly.

• Type: ReactNode
• Description: Link content — text, icons, components

<Link routeName="dashboard">
  <DashboardIcon />
  <span>Dashboard</span>
</Link>

• HTML element: <a>
• Attributes: href, className, onClick

<a href="/users/123" class="nav-link active"> User Profile </a>

<Link routeName="home" className="nav-link" activeClassName="nav-link--current">
  Home
</Link>

.nav-link {
  color: #666;
  text-decoration: none;
}

.nav-link--current {
  color: #000;
  font-weight: bold;
}

• Semantics: Native <a> element with correct href
• Keyboard: Tab for focus, Enter for navigation
• Screen readers: Read as standard link

• useRouter — getting router instance from context

• Renders <a> element with correct href
• Does not have active class if route is inactive
• Adds active class if route is active
• Works with router's default route

• Works correctly when router not started (href is generated)
• Works with defaultRoute router option

• Automatic router retrieval from context
• Memoized rendering — only re-renders when active state or props change

For applying navigation to any element without using Link, framework-specific directives are available:

• Solid: use:link directive
• Vue: v-link directive
• Svelte: createLinkAction factory
• Angular: realLink directive on <a> elements, [realLinkActive] for active class on any element

These provide low-level navigation control for custom elements.

Angular note: Angular uses the realLink directive on <a> elements instead of a <Link> component. Inputs: routeName, routeParams, routeOptions, activeClassName, activeStrict, ignoreQueryParams. The directive also checks target="_blank" and skips client-side navigation for external links.

import { Link } from "@real-router/react";

function Navigation() {
  return (
    <nav>
      <Link routeName="home">Home</Link>
      <Link routeName="about">About</Link>
      <Link routeName="contact">Contact</Link>
    </nav>
  );
}

function UsersList({ users }) {
  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>
          <Link routeName="users.profile" routeParams={{ id: user.id }}>
            {user.name}
          </Link>
        </li>
      ))}
    </ul>
  );
}

function MainNav() {
  return (
    <nav className="main-nav">
      <Link
        routeName="dashboard"
        className="main-nav__link"
        activeClassName="main-nav__link--active"
      >
        Dashboard
      </Link>
      <Link
        routeName="settings"
        className="main-nav__link"
        activeClassName="main-nav__link--active"
      >
        Settings
      </Link>
    </nav>
  );
}

function SectionNav() {
  return (
    <nav>
      {/* Active for /users, /users/list, /users/123 */}
      <Link routeName="users" activeStrict={false}>
        All Users
      </Link>

      {/* Active ONLY for /users */}
      <Link routeName="users" activeStrict={true}>
        Users Index
      </Link>
    </nav>
  );
}

function TrackedLink({ routeName, children }) {
  return (
    <Link
      routeName={routeName}
      onClick={() => {
        analytics.track("link_clicked", { route: routeName });
      }}
    >
      {children}
    </Link>
  );
}

Tip: To handle navigation results (success/error), call router.navigate() directly instead of using Link. The navigate() method returns a Promise<State>.

// Don't use Link outside RouterProvider
function Bad() {
  return <Link routeName="home">Home</Link>; // Error!
}

// Wrap in RouterProvider
function Good() {
  return (
    <RouterProvider router={router}>
      <Link routeName="home">Home</Link>
    </RouterProvider>
  );
}

// Don't use for external URLs
function Bad() {
  return <Link routeName="https://google.com">Google</Link>;
}

// Use regular <a> for external links
function Good() {
  return (
    <a href="https://google.com" target="_blank" rel="noopener">
      Google
    </a>
  );
}

// Don't pass router — it's ignored
function Bad() {
  const myRouter = useRouter();
  return (
    <Link router={myRouter} routeName="home">
      Home
    </Link>
  );
}

// Link gets router automatically
function Good() {
  return <Link routeName="home">Home</Link>;
}

// routeOptions supported directly on Link
function ReplaceNavigation() {
  return (
    <Link routeName="checkout" routeOptions={{ replace: true }}>
      Checkout
    </Link>
  );
}

Comparison of @real-router/react/Link with react-router5/Link from router5.

Props remain compatible:

// routeOptions works directly on Link (no change needed from router5)
<Link routeName="checkout" routeOptions={{ replace: true }}>
  Checkout
</Link>

• Was: HOC pattern — withRouter(BaseLink) creates component that gets router via routerContext.Consumer
• Now: Hook pattern — Link uses useRouter() and passes to BaseLink

• Simpler code: No intermediate HOC layer
• Better typing: TypeScript works better with hooks than HOC
• Fewer nesting levels: Simpler structure in DevTools
• Modern React: Uses hooks instead of render props/HOC

• withRouter HOC: No longer needed — use useRouter() hook directly
• ConnectedLink: Was withRoute(BaseLink) — use Link + useRoute() instead
• BaseLink: Merged into Link — all props including routeOptions are supported directly

• Update package import from react-router5 to @real-router/react
• routeOptions works on Link directly — no changes needed
• If successCallback/errorCallback was used — use router.navigate() which returns Promise<State>
• If withRouter HOC was used — replace with useRouter() hook
• If ConnectedLink was used — replace with Link or custom component with useRoute()
• If BaseLink was used — replace with Link inside RouterProvider

1. Update imports: Replace react-router5 with @real-router/react
2. routeOptions: Works on Link directly — no migration needed
3. Replace callbacks: If successCallback/errorCallback was used — call router.navigate() directly and handle the returned Promise<State>
4. Replace HOC: withRouter → useRouter() hook
5. Remove ConnectedLink: Use Link or create custom component with useRoute()
6. Remove BaseLink: Use Link inside RouterProvider — all props supported directly

Maximum severity: LOW — successCallback/errorCallback removed in favor of router.navigate() returning Promise<State>. routeOptions is supported directly on Link.