# Link Provider

## Usage

Wraps your app to replace the default `<a>` tag with a framework-specific link component (e.g. Vue Router's `RouterLink`) for client-side routing across all Astryx components.

```ts
import { LinkProvider } from '@astryx-vue/core/LinkProvider'
```

The component receives `href` and `to`, so a router link can read whichever one it expects. A single component's own `as` prop still wins over the provider. `useLinkComponent()` reads the provider from a descendant when you render a link yourself.

## Examples

Common configurations, variations, and states.

### Link Provider — Custom Link Component

Routes every Astryx link through a custom component that intercepts the click, the hook frameworks like Vue Router use for client-side navigation. Click the link to see the custom handler fire instead of a full-page load.

```vue
<script setup lang="ts">
import { Link } from '@astryx-vue/core/Link'
import { LinkProvider } from '@astryx-vue/core/LinkProvider'
import { defineComponent, h, ref } from 'vue'

const intercepted = ref<string | null>(null)

/**
 * A stand-in for a framework router link (Vue Router's `RouterLink`, Nuxt's
 * `NuxtLink`). Instead of a full-page navigation it intercepts the click and
 * hands the destination to its own handler — the same hook real routers use.
 * Here it only reports the destination so the swap is observable.
 */
const RouterLink = defineComponent({
  name: 'RouterLink',
  inheritAttrs: false,
  props: {
    href: { type: String, default: undefined },
    to: { type: String, default: undefined },
  },
  setup(props, { attrs, slots }) {
    return () => h('a', {
      ...attrs,
      href: props.href ?? props.to,
      onClick: (event: MouseEvent) => {
        event.preventDefault()
        ;(attrs.onClick as ((event: MouseEvent) => void) | undefined)?.(event)
        intercepted.value = props.to ?? props.href ?? ''
      },
    }, slots.default?.())
  },
})
</script>

<template>
  <div class="link-provider-preview">
    <LinkProvider :component="RouterLink">
      <Link href="/dashboard" is-standalone>
        Go to dashboard
      </Link>
    </LinkProvider>
    <p class="link-provider-preview__status">
      {{ intercepted ? `RouterLink intercepted navigation to: ${intercepted}` : 'Click the link to try the custom component.' }}
    </p>
  </div>
</template>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `component` | `LinkComponentType` | — | Link component to use for all link elements in the subtree (e.g. `RouterLink` or `NuxtLink`). It receives `href` and `to`. A component's own `as` prop still wins. Required. |

## Slots

| Slot | Description |
| --- | --- |
| `default` | Content rendered with the link provider. |

## Exports

| Export | Type | Description |
| --- | --- | --- |
| `useLinkComponent` | `() => ComputedRef` | The link component the nearest provider supplies, or `undefined` outside one. Use it as `props.as ?? linkComponent.value` so an explicit `as` still wins. |

## Components that follow the provider

These render their link through the provider unless they are given their own `as`:

- `Link`, `Button`, `Avatar`, `Token`
- `NavItem`, `NavMenuItem`, `NavHeadingMenuItem`, `SideNavHeading`, `TopNavItem`, `TopNavMegaMenuItem`, `TopNavMegaMenuFeaturedCard`
- `BreadcrumbItem`, `Tab`, `Item` (List)
- `DropdownMenuItem`, `ContextMenuItem`, `MoreMenuRow`, `TreeListItem`

Not routed through the provider: the `AppShell` skip link, `Outline` links (in-page anchors), `ClickableCard` (its overlay control is a visually hidden anchor), and links rendered from Markdown.

## Native attributes

The component renders no element of its own, so <code>class</code> and <code>style</code> are not forwarded.