useLink() | Vue Router - Custom Link Behavior Made Easy 🔗

Build custom navigation components - Access RouterLink's internal logic without the rendering constraints!

🎯 Function Overview

The useLink() composable gives you direct access to the internal behavior of RouterLink without being tied to its default rendering. This is perfect for creating custom navigation components with complete control over the UI while maintaining all the smart routing capabilities.

📋 Basic Usage

function useLink<Name extends string | symbol = string | symbol>(
  props: UseLinkOptions<Name>
): UseLinkReturn<Name>

🔧 Parameters

Parameter	Type	Description
props	UseLinkOptions<Name>	Configuration options including the target location and navigation behavior

📤 Returns

• Type: UseLinkReturn<Name>
• Description: An object containing all the reactive link properties and methods

💡 When to Use This Function

🎨 Custom UI Components

Create navigation elements that don't look like traditional links:

<template>
  <button 
    @click="navigate"
    :class="{ active: isActive }"
    :aria-current="isActive ? 'page' : undefined"
  >
    <slot />
  </button>
</template>

<script setup>
import { useLink } from 'vue-router'

const props = defineProps({
  to: [String, Object],
  replace: Boolean
})

const { navigate, isActive } = useLink(props)
</script>

🔧 Advanced Navigation Logic

Implement complex navigation behavior beyond standard links:

const { navigate, href, route, isActive, isExactActive } = useLink({
  to: '/dashboard',
  replace: false
})

// Custom navigation with additional logic
function customNavigate() {
  if (shouldNavigate()) {
    navigate()
    trackNavigation()
  }
}

🛠️ Practical Examples

Example 1: Custom Button Navigation

<template>
  <button
    class="nav-button"
    :class="{ 
      'nav-button--active': isActive,
      'nav-button--exact-active': isExactActive 
    }"
    @click="handleClick"
    :disabled="isDisabled"
  >
    <span class="nav-button__icon">
      <slot name="icon" />
    </span>
    <span class="nav-button__text">
      <slot />
    </span>
  </button>
</template>

<script setup>
import { computed } from 'vue'
import { useLink } from 'vue-router'

const props = defineProps({
  to: [String, Object],
  replace: Boolean,
  disabled: Boolean
})

const { navigate, isActive, isExactActive, href } = useLink(props)

const isDisabled = computed(() => props.disabled || isActive.value)

function handleClick(event) {
  if (!isDisabled.value) {
    navigate(event)
    // Emit custom event
    emit('navigate', { to: props.to, href: href.value })
  }
}
</script>

<style scoped>
.nav-button {
  padding: 12px 16px;
  border: none;
  background: transparent;
  cursor: pointer;
  transition: all 0.2s ease;
}

.nav-button--active {
  background: #007bff;
  color: white;
}

.nav-button--exact-active {
  box-shadow: 0 2px 4px rgba(0, 123, 255, 0.3);
}

.nav-button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
</style>

Example 2: Breadcrumb Navigation

<template>
  <nav class="breadcrumb">
    <ol>
      <li v-for="(crumb, index) in breadcrumbs" :key="index">
        <component
          :is="crumb.to ? 'a' : 'span'"
          :href="crumb.to ? href : undefined"
          @click="crumb.to ? navigate(crumb.to) : null"
          :class="{ 'breadcrumb__item--active': !crumb.to }"
        >
          {{ crumb.label }}
        </component>
        <span v-if="index < breadcrumbs.length - 1" class="breadcrumb__separator">
          /
        </span>
      </li>
    </ol>
  </nav>
</template>

<script setup>
import { computed } from 'vue'
import { useLink, useRoute } from 'vue-router'

const route = useRoute()

const breadcrumbs = computed(() => {
  const paths = route.path.split('/').filter(Boolean)
  
  return paths.map((path, index) => {
    const fullPath = '/' + paths.slice(0, index + 1).join('/')
    const isLast = index === paths.length - 1
    
    return {
      label: path.charAt(0).toUpperCase() + path.slice(1),
      to: isLast ? null : fullPath
    }
  })
})

// Custom navigation function for breadcrumbs
function navigate(to) {
  const { navigate: linkNavigate } = useLink({ to })
  linkNavigate()
}
</script>

🔍 Return Value Properties

📊 Reactive Properties

Property	Type	Description
navigate	Function	Function to trigger navigation
isActive	boolean	Whether the link is active
isExactActive	boolean	Whether the link is exactly active
href	string	Resolved URL href
route	RouteLocationNormalizedLoaded	The target route object

🎯 Best Practices

✅ Do Use When

• Building custom navigation components
• Creating non-link navigation elements (buttons, cards, etc.)
• Implementing complex navigation logic
• Need fine-grained control over navigation behavior

❌ Avoid When

• Simple link navigation (use <RouterLink> instead)
• Basic navigation without custom UI requirements
• Performance-critical simple navigation

🔧 Advanced Usage Patterns

Pattern 1: Programmatic Navigation Control

const { navigate, isActive } = useLink({
  to: '/target',
  replace: false
})

// Control navigation with additional conditions
function controlledNavigate() {
  if (userHasPermission()) {
    navigate()
  } else {
    showPermissionError()
  }
}

Pattern 2: Multi-step Navigation

const navigation = useLink({ to: '/wizard/step2' })

async function handleWizardNavigation() {
  // Validate current step
  if (await validateCurrentStep()) {
    navigation.navigate()
  } else {
    showValidationErrors()
  }
}

Pattern 3: Analytics Integration

const { navigate, href } = useLink({ to: '/target' })

function trackAndNavigate(event) {
  // Send analytics before navigation
  analytics.track('link_click', {
    href: href.value,
    timestamp: Date.now()
  })
  
  navigate(event)
}

📚 Related Components & Functions

• RouterLink - The standard link component
• useRouter() - Access router instance for programmatic navigation
• useRoute() - Access current route information

🚀 Performance Considerations

⚡ Lazy Evaluation

// Only create link when needed
const link = computed(() => 
  isNavigationNeeded.value ? useLink(props) : null
)

🔄 Memoization

import { memoize } from 'lodash-es'

const createLink = memoize((to) => useLink({ to }))

// Reuse link instances for same destinations
const homeLink = createLink('/home')
const aboutLink = createLink('/about')

---

💡 Pro Tip

Combine useLink() with Vue's defineProps and TypeScript for type-safe custom navigation components that are both powerful and maintainable!

Ready to build custom navigation experiences? Start using useLink() for complete control over your app's navigation behavior! 🔗