Link

The Link and NavLink primitives extend standard HTML anchor links by integrating language locales, base directories, and SPA route navigation.

You almost never need them in MDX content — regular Markdown links work fine there. Reach for Link / NavLink only inside custom React components where you want:

• SPA-style route transitions (no full page reload).
• Automatic locale + version prefixing on internal href.
• Active-state styling via the NavLink's render function.

Both render as a normal <a> under the hood.

Import

import { Link, NavLink } from 'boltdocs/primitives'

Quick Start

Create localized, SPA-aware routing links:

import { Link, NavLink } from 'boltdocs/primitives'

export default function SidebarNav() {
  return (
    <div className="flex flex-col gap-2">
      {/* 1. Standard localized navigation */}
      <Link href="/getting-started" className="text-primary-500 hover:underline">
        Getting Started
      </Link>

      {/* 2. NavLink with automatic active state highlighting */}
      <NavLink
        href="/api/config-reference"
        className={({ isActive }) =>
          `px-3 py-1 rounded text-sm ${isActive ? 'bg-primary-500 text-white' : 'text-muted hover:bg-soft'}`
        }
      >
        Config Reference
      </NavLink>
    </div>
  )
}

Under-the-Hood Mechanics

• Localization: Direct href strings (like /getting-started) are automatically parsed and translated through the useLocalizedTo hook. For instance, on a Spanish localized page, /getting-started is transformed to /es/getting-started transparently.
• SPA Routing: Internal link clicks intercept default browser navigation to perform fast client-side routing, preventing full page reloads.

Component Props

Link Props

Inherits all standard HTML anchor (<a>) element attributes:

NavLink Props

Extends standard Link properties:

Pitfalls

• NavLink's render function isn't React-stateful. The isActive boolean is evaluated synchronously per render. Don't trigger heavy side-effects in the function body — use it only for class-name computation.
• Hard-coding locales in href defeats the hook. If the user is on /es/docs/guide and you pass a raw /docs/guide href, useLocalizedTo re-localizes it. If you want a non-localized link, prefix with https:// or use a plain <a>.
• end={true} matters for index pages. Without it, /docs is "active" when the current path is /docs/installation. Use end whenever the link points to a section root.