Link Component
Relevant source files
The following files were used as context for generating this wiki page:
The Link component is a core navigation utility in wouter-vue designed to facilitate seamless, client-side transitions between routes without triggering a full page reload. It acts as an abstraction over the standard HTML anchor (<a>) tag, integrating directly with the router's location state and navigation logic. Sources: src/components/Link.tsx:1-5, README.md:144-148
By leveraging Vue 3's Composition API, the Link component provides reactive active state detection, allowing developers to style links differently when their target path matches the current browser location. It supports both standard anchor rendering and an "as-child" mode for custom component wrapping. Sources: src/components/Link.tsx:90-95, README.md:104
Component Architecture and Props
The Link component is defined as a functional-style component using the setup hook. It accepts several props that control its navigation behavior and rendering style. Sources: src/components/Link.tsx:28-40
Support Properties
| Prop | Type | Description |
|---|---|---|
href | String | The target URL path. Takes precedence over to. |
to | String | Alias for the target URL path. |
onClick | Function | Custom click handler executed before navigation. |
asChild | Boolean | When true, the component delegates rendering to its immediate child. |
replace | Boolean | If true, uses history.replaceState instead of pushState. |
Sources: src/components/Link.tsx:30-36
Navigation Logic
The component manages navigation through an internal onClick handler. This handler includes built-in checks to ensure standard browser behaviors (like opening links in new tabs with Ctrl+Click) are preserved. Sources: src/components/Link.tsx:55-65
The logic ensures that navigation only occurs if the event has not been prevented by a custom handler and the click is a standard left-click without modifier keys. Sources: src/components/Link.tsx:58-75
Active State Detection
The component reactively determines if it is "active" by comparing the normalized target path against the current router path. Sources: src/components/Link.tsx:91-95
Scoped Slot API
Developers can access the active state through a scoped slot. This is particularly useful for applying conditional CSS classes or changing the internal content of the link based on the current route. Sources: src/components/Link.tsx:102-113, examples/example/README.md:83-89
<Link href="/about">
<template #default="{ isActive }">
<span :class="{ 'text-bold': isActive }">About Us</span>
</template>
</Link>
Sources: src/components/Link.tsx:105-110
Rendering Modes
The component supports two distinct rendering strategies:
1. Default Anchor Rendering
By default, the component renders a standard <a> tag. It automatically merges attributes (like class or data-testid) from the parent context to the rendered element. Sources: src/components/Link.tsx:159-168
2. "asChild" Pattern
When the asChild prop is enabled, the component does not render its own tag. Instead, it clones its single child element and injects the necessary navigation props (href and onClick) into it. Sources: src/components/Link.tsx:123-145
This mode requires exactly one child element; otherwise, a development warning is issued. Sources: src/components/Link.tsx:132-138
Integration and Usage
The Link component is typically used alongside the Route and Router components to build a complete navigation system. Sources: README.md:141-158
Path Resolution
Paths are resolved based on the current Router context. If the path starts with ~, it is treated as relative to the root; otherwise, it is appended to the router's base path. Sources: src/components/Link.tsx:78-85
Example Implementations
- Simple Navigation: Used in test routes to navigate between numbered pages. Sources: examples/example/src/pages/routes/Route10.vue:6
- Main Navigation: Used in home pages for primary site sections. Sources: examples/example/src/pages/HomePage.vue:26-29
- Back Buttons: Frequently used to return to the root path. Sources: examples/example/src/pages/AboutPage.vue:85
The Link component is essential for maintaining the performance advantages of wouter-vue, ensuring that transitions are handled by the lightweight reactivity system rather than the browser's document loader. Sources: README.md:16-25