Links & navigation

Use real links for navigation and let Goribu enhance them after hydration.

Link

Import Link from goribu. It renders an anchor that works before JavaScript loads:

import { Link } from "goribu";

// Keep normal anchor behavior such as opening a link in a new tab.
export default function Menu() {
  return (
    <nav>
      <Link href="/posts">Posts</Link>
      <Link href="/login" replace>Sign in</Link>
      <Link href="/reports" prefetch={false}>Reports</Link>
    </nav>
  );
}

replace updates the current history entry instead of adding one. prefetch defaults to true: hovering briefly or pressing an eligible link starts loading its destination. Use prefetch={false} when that is not useful.

Link accepts normal anchor props, including target, download, and event handlers. Your onClick runs first and can cancel navigation with preventDefault().

NavLink

Use NavLink for a menu that needs active styling:

import { NavLink } from "goribu";

// Highlight the current section using pathname-based matching.
export default function SettingsMenu() {
  return (
    <nav>
      <NavLink
        href="/settings"
        className={({ isActive }) => isActive ? "active" : undefined}
      >
        Settings
      </NavLink>
      <NavLink href="/settings/profile" end>Profile</NavLink>
    </nav>
  );
}

An active link gets aria-current="page". Matching ignores query strings and hashes, respects segment boundaries, and normally includes child paths. end requires the exact pathname; / is always exact. Let NavLink own aria-current.

Navigate from an event

Use navigate() when navigation follows an action with no meaningful anchor:

import { navigate } from "goribu";

// Continue after an application-controlled event.
export async function continueToDashboard() {
  await navigate("/dashboard", { replace: true });
}

It returns a Promise. Prefer Link when users should be able to copy the URL, open another tab, or navigate without JavaScript.

What runs on the server

A client transition still goes through ordinary route matching, middleware, GET handlers, cookies, and request-scoped resources. Goribu loads the matching client page module before committing the UI and URL.

The navigation endpoint under /_goribu/ is internal. Use Link, NavLink, or navigate rather than calling it yourself. There is no public router store or navigation hook to keep in sync.

History and scrolling

New navigations add one history entry by default. Redirect chains commit the final destination, and replace changes the current entry. Browser Back and Forward reuse existing entries.

A new page scrolls to its matching hash target or to the top. Back and Forward restore saved scroll positions. Same-document anchors retain normal browser behavior.

Native behavior and fallbacks

External links, downloads, non-default targets, modifier clicks, and same-document hashes remain browser-owned. Goribu enhances only eligible same-origin HTTP(S) navigation.

If a transition cannot safely complete, Goribu loads the target document. API responses, error pages, missing pages, stale modules, and invalid protocol results can take this path. A newer navigation also prevents an older request from replacing the page you have moved to.