Link
Localized link anchors integrated with the router.
The Link and NavLink primitives extend standard HTML anchor links by integrating language locales, base directories, and SPA route navigation.
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>
)
}
Internal Mechanics
- Localization: Direct
hrefstrings (such as/getting-started) are parsed and automatically translated through theuseLocalizedTohook. For example, on a Spanish-localized page,/getting-startedis transparently transformed to/es/getting-started. - SPA Routing: Clicks on internal links intercept the browser's default navigation to perform fast client-side routing, preventing full page reloads.
Component Props
Link Props
Inherits all standard HTML anchor (<a>) element attributes:
| Property | Type | Default | Description |
|---|---|---|---|
href | string | undefined | Target route path (e.g., /docs/getting-started). |
prefetch | 'hover' | 'none' | 'hover' | Preload strategy for router link targets. |
NavLink Props
Extends the standard Link props:
| Property | Type | Default | Description |
|---|---|---|---|
href | string | undefined | Target route path. |
end | boolean | false | When set to true, the link is only highlighted as active when the routes match exactly. |
className | string | ((props: { isActive: boolean }) => string) | undefined | Style class name, supporting conditional logic functions. |
children | ReactNode | ((props: { isActive: boolean }) => ReactNode) | undefined | Child nodes, supporting conditional render functions. |
Customization & states
Link is style-neutral — it renders a standard <a> with localized routing, prefetching, and SPA navigation, but no visuals. Its data-* props pass straight through to the anchor. NavLink adds route matching: when the current route matches href, the link is treated as active, and you receive that state through the className / children render functions (a plain active class is appended when you pass a string className).
| State / Slot | Mechanism |
|---|---|
NavLink className (function) | Receives { isActive } — return the classes for the active / inactive states |
NavLink children (function) | Receives { isActive } for conditional content |
active class | Appended to NavLink when the current route matches (when className is a string) |
end prop | true matches only the exact path; false (default) matches any path that starts with it |
data-* attributes | Pass through from props to the <a> element |
ref | Forwarded to the rendered anchor |
Tailwind v4:
<NavLink
href="/docs/guides"
className={({ isActive }) =>
`px-3 py-1 rounded text-sm ${
isActive ? 'bg-primary-500/10 text-primary-400' : 'text-muted hover:bg-soft'
}`
}
>
Guides
</NavLink>
Or vanilla CSS:
a.active {
color: var(--color-primary-400);
background: color-mix(in srgb, var(--color-primary-500) 10%, transparent);
}
