<!-- Protocore Design System — Link -->
# Link

- **Category:** Typography (`typography`)
- **Slug:** `typography/link`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { Link } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/typography/link

> Inline text link — ink with a control-hairline underline that inks in on hover.

## When to use it

Use `Link` for inline navigation inside a run of text — a word or phrase that takes the reader elsewhere. It lives in the flow of a `Text` paragraph.

For a standalone call to action — something the user *acts on* rather than reads through — use `Button` (with `variant="ghost"` if it should look understated). The rule of thumb: if it navigates within prose, it's a `Link`; if it's a discrete action target, it's a `Button`. When wrapping a framework's own link component, always pass `asChild` so routing keeps working instead of a full page load.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | no | — | Merge props onto the single child instead of rendering an `<a>` (framework links). |
| `className` | `string` | no | — | — |
| `external` | `boolean` | no | — | Treat as an external link — opens in a new tab, adds `rel` + a `↗` marker. |
| `style` | `CSSProperties` | no | — | — |

## Examples

### Basics

`Link` is an inline anchor: ink-coloured text with a faint hairline underline that inks in to full contrast on hover.

```tsx
import { Link, Text } from "@protocore/pds";

export default function LinkBasics() {
  return (
    <Text>
      Read the <Link href="/docs/endpoint">endpoint reference</Link> before you wire up your first
      message.
    </Text>
  );
}
```

### External

`external` opens the link in a new tab, adds `rel="noreferrer noopener"`, and appends a muted ↗︎ marker.

```tsx
import { Link, Text } from "@protocore/pds";

export default function LinkExternal() {
  return (
    <Text>
      The full spec lives in the{" "}
      <Link href="https://example.com/whitepaper" external>
        protocol whitepaper
      </Link>{" "}
      — external links open in a new tab and carry a ↗︎ marker.
    </Text>
  );
}
```

## Guidelines

**Do**

- Use `Link` for inline, in-prose navigation.
- Pass `external` for off-site destinations so they open safely in a new tab.
- Use `asChild` to wrap a Next.js / React Router link and keep SPA routing.
- Write descriptive link text that makes sense out of context.

**Don't**

- Don't use a `Link` as a primary call to action — that is `Button`.
- Don't write "click here"; the linked phrase should describe the target.
- Don't set `external` on same-origin links — it needlessly opens a new tab.
- Don't nest interactive elements inside a `Link`.

## Accessibility

**Keyboard**

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the link. |
| `Enter` | Activates the link. |

**Notes**

- Renders a native `<a>` (or, with `asChild`, your anchor), so focus, activation, and context-menu behaviour are the browser's.
- A visible focus ring is applied on `:focus-visible` per the system focus policy.
- The ↗︎ external marker is `aria-hidden`; convey "opens in a new tab" in the link text when it matters.

## Related

`text`, `button`, `code`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/