# Link

> An inline text link — for a link that should look like a button, use Button with href instead.

URL: https://apogee.avaui.dev/docs/link
Last updated: 2026-10-15

An inline text link — for a link that should look like a button, use Button with href instead.

Last updated October 15, 2026

```astro
<Link href="#">Default link</Link>
<Link href="#" underline="hover">Hover underline</Link>
```

## Add

```sh
npx @ava-ui/apogee add link
```

No Apogee dependencies.

## Usage

```astro
---
import Link from '@/components/apogee/Link/Link.astro'
---
<Link href="/docs">Read the docs</Link>
```

## API

`@composable` — exposed to Content Editors in AVA. Any other native `<a>` attribute (e.g. `download`, `hreflang`) passes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Required. Link destination. |
| `color` | `'primary' \| 'neutral' \| 'critical' \| 'positive' \| 'warning' \| 'inherit'` | `'primary'` | Text colour; `inherit` takes the surrounding colour. |
| `underline` | `'always' \| 'hover' \| 'none'` | `'always'` | Underline behaviour. |
| `disabled` | `boolean` | `false` | No `href`, `aria-disabled`, dimmed. |
| `external` | `boolean` | `false` | Opens in a new tab (`target="_blank"`) with `rel="noopener noreferrer"`. |
| `class` | `string` | — | Extra classes, merged last. |

## Variants

Every `underline` value:

```astro
<Link href="#" underline="always">Always underlined</Link>
<Link href="#" underline="hover">Underline on hover</Link>
<Link href="#" underline="none">Never underlined</Link>
```

## Colours

Every `color`; `inherit` takes the colour of the text around it.

```astro
<Link href="#" color="primary">Primary</Link>
<Link href="#" color="neutral">Neutral</Link>
<Link href="#" color="critical">Critical</Link>
<Link href="#" color="positive">Positive</Link>
<Link href="#" color="warning">Warning</Link>
<span class="text-critical">Inside critical text, <Link href="#" color="inherit">inherit</Link> matches it.</span>
```

## States

-   **Hover** — colour shifts to `--background-primary-highlighted`; `underline="hover"` reveals its underline.
-   **Focus** — a visible `focus-visible` ring (`--border-primary`).

## Examples

With icons in the `start` / `end` slots (sized to the text):

```astro
<Link href="#"><Mail slot="start" /> Email us</Link>
<Link href="#" external>Docs<ExternalLink slot="end" /></Link>
```

Semantic colours and a disabled link:

```astro
<Link href="#" color="critical">Delete</Link>
<Link href="#" color="positive">Approved</Link>
<Link href="#" color="warning">Pending</Link>
<Link href="#" disabled>Unavailable</Link>
```

External link, with a trailing icon as the visual cue:

```astro
<Link href="https://example.com" external underline="hover">Visit example.com <ExternalLink class="inline size-3.5" /></Link>
```

## Accessibility

-   Real `<a href>` — full keyboard and assistive-tech support; reachable via `Tab`, activates with `Enter`.
-   Focus ring always visible on keyboard focus.
-   `external` sets `rel="noopener noreferrer"` (the new tab can’t access `window.opener`) — pair it with a visual cue (e.g. an icon) so users aren’t surprised it left the site.
-   No JS.

## Tokens

| Token | Used for |
| --- | --- |
| `--foreground-primary` | Link colour |
| `--outline-color-focus` | Focus ring |

## Do / Don’t

-   **Do** use `Link` for inline, in-sentence navigation; use `Button` with `href` for a link that should look like a call-to-action.
-   **Do** set `external` (and ideally show an icon) for links that leave the site.
-   **Don’t** rely on colour alone to distinguish a link from surrounding text — keep `underline="always"` (the default) for body copy.
-   **Don’t** use `underline="none"` outside nav/UI chrome where the link is already visually distinct (e.g. a menu item).

## Content

-   Link text describes the destination (“Read the pricing guide”), never “click here” or a bare URL.
-   Keep it concise — a few words, not a full sentence.

## Related

[

ActionableThe bare interactive primitive. A button, link or focusable div with the focus ring and disabled handling, nothing else.

](https://apogee.avaui.dev/docs/actionable)[

ButtonTriggers an action. Renders a <button>, or an <a> when href is set. Hue, fill and height are three separate props.

](https://apogee.avaui.dev/docs/button)[

NavLinkA navigation link that auto-detects and styles the current route, with prefix matching, external links and a collapsible NavGroup.

](https://apogee.avaui.dev/docs/nav-link)