# Link

A styled anchor that opens external links in a new tab, with an arrow to say so.

Source: [link.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/link.tsx)

```tsx
"use client";

import { Link } from "@/components/ui/link";
import { preventNavigation } from "@/examples/data";

export default function LinkBasic() {
  return (
    <p className="max-w-sm text-sm text-muted-foreground">
      Deploys roll out region by region. Read the{" "}
      <Link href="#" onClick={preventNavigation}>
        rollouts guide
      </Link>{" "}
      to choose the order, or check the{" "}
      <Link href="https://example.com/status" onClick={preventNavigation}>
        status page
      </Link>{" "}
      for incidents.
    </p>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/link
```

## Usage

```tsx
import { Link } from "@/components/ui/link";

export function StatusNote() {
  return (
    <p>
      Check the <Link href="https://example.com/status">status page</Link> for incidents.
    </p>
  );
}
```

A link whose `href` is an absolute URL, such as `https://example.com`, opens in a new tab. It gets
`rel="noopener noreferrer"` and an arrow after its text, and screen readers announce "(opens in a
new tab)" after its name. Relative paths, fragments, `mailto:` and `tel:` links open in place.

Link can render in a server component. Use it for navigation. For an action that looks like a link,
use a [Button](https://ui.jarv.is/components/button.md) with `variant="link"`.

## Examples

### Variants

`default` underlines the link in the foreground color. `muted` matches the links inside other
components' descriptions, such as a [Card](https://ui.jarv.is/components/card.md)'s. `plain` keeps the color of its
surroundings and underlines the link only on hover, for lists of links such as a footer.

```tsx
"use client";

import { Link } from "@/components/ui/link";
import { preventNavigation } from "@/examples/data";

export default function LinkVariants() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm">
      <Link href="#" onClick={preventNavigation}>
        Default
      </Link>
      <Link href="#" variant="muted" onClick={preventNavigation}>
        Muted
      </Link>
      <Link href="#" variant="plain" onClick={preventNavigation}>
        Plain
      </Link>
    </div>
  );
}
```

### External links

Pass `external` to open any link in a new tab, such as a PDF on your own site, or
`external={false}` to keep an absolute URL to your own site in the same tab. A `target` you pass
yourself always wins, and a link with `target="_blank"` shows the arrow too.

An external link adds the `rel` you pass to its own, so `rel="me"` on a link to your profile
renders `rel="noopener noreferrer me"`. To keep the referrer, pass `external={false}` with your own
`target="_blank"` and `rel="noopener"`.

```tsx
"use client";

import { Link } from "@/components/ui/link";
import { preventNavigation } from "@/examples/data";

export default function LinkExternal() {
  return (
    <div className="flex flex-col items-start gap-3 text-sm">
      <Link href="https://example.com/docs" onClick={preventNavigation}>
        API reference
      </Link>
      <Link href="/reports/2025.pdf" external onClick={preventNavigation}>
        Annual report (PDF)
      </Link>
      <Link href="https://example.com/pricing" external={false} onClick={preventNavigation}>
        Pricing
      </Link>
    </div>
  );
}
```

### Without the arrow

Pass `externalIcon={false}` to hide the arrow where every link opens in a new tab, such as a row of
links to other sites. Screen readers still announce `newTabLabel`.

```tsx
"use client";

import { Link } from "@/components/ui/link";
import { preventNavigation } from "@/examples/data";

export default function LinkWithoutIcon() {
  return (
    <nav className="flex flex-wrap items-center gap-4 text-sm">
      <Link
        href="https://example.com/changelog"
        variant="muted"
        externalIcon={false}
        onClick={preventNavigation}
      >
        Changelog
      </Link>
      <Link
        href="https://example.com/community"
        variant="muted"
        externalIcon={false}
        onClick={preventNavigation}
      >
        Community
      </Link>
      <Link
        href="https://example.com/status"
        variant="muted"
        externalIcon={false}
        onClick={preventNavigation}
      >
        Status
      </Link>
    </nav>
  );
}
```

## Routers

To navigate with your router, pass its link to `render`. Link merges its class names and
attributes into the router's `<a>`. It reads `href` to decide whether a link is external, so a
router link that takes `to` stays in the same tab. Use Link with `href` for external URLs.

**Next.js**

Wrap Link once with `next/link`, so `href` reaches both of them.

```tsx title="components/app-link.tsx"
import NextLink from "next/link";

import { Link, type LinkProps } from "@/components/ui/link";

export function AppLink({ href, ...props }: LinkProps & { href: string }) {
  return <Link href={href} render={<NextLink href={href} />} {...props} />;
}
```

**Vite**

With React Router, wrap Link once with its `Link`, which sets `href` from `to`.

```tsx title="src/components/app-link.tsx"
import { Link as RouterLink } from "react-router";

import { Link, type LinkProps } from "@/components/ui/link";

export function AppLink({ to, ...props }: LinkProps & { to: string }) {
  return <Link render={<RouterLink to={to} />} {...props} />;
}
```

**TanStack Start**

Pass Link to TanStack Router's `createLink`. The result takes the router's type-checked `to`,
`params` and `search` alongside Link's own props.

```tsx title="src/components/app-link.tsx"
import { createLink } from "@tanstack/react-router";

import { Link } from "@/components/ui/link";

export const AppLink = createLink(Link);
```

```tsx
import { AppLink } from "@/components/app-link";

export function PostLink({ postId }: { postId: string }) {
  return (
    <AppLink to="/posts/$postId" params={{ postId }} variant="muted">
      Read the post
    </AppLink>
  );
}
```

A link with `aria-current="page"` turns the foreground color. TanStack Router sets it on the
active link. With other routers, set it yourself.

## Props

| Part | Extends |
| --- | --- |
| `Link` | `<a>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### Link

| Prop            | Type                                                     | Default                  | Description                                                                                                                                                                               |
| --------------- | -------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variant?`      | `"default" \| "muted" \| "plain"`                        | `"default"`              |                                                                                                                                                                                           |
| `external?`     | `boolean`                                                | —                        | Opens the link in a new tab and adds `noopener noreferrer` to its `rel`. Defaults to `true` when `href` is an absolute URL, such as `https://example.com`, and `false` otherwise.         |
| `externalIcon?` | `boolean`                                                | `true`                   | Shows an arrow after a link that opens in a new tab.                                                                                                                                      |
| `newTabLabel?`  | `string`                                                 | `"(opens in a new tab)"` | The text screen readers announce after a link that opens in a new tab. Pass an empty string to leave it out.                                                                              |
| `className?`    | `string`                                                 | —                        | CSS class applied to the element.                                                                                                                                                         |
| `style?`        | `React.CSSProperties`                                    | —                        | Style applied to the element.                                                                                                                                                             |
| `render?`       | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —                        | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
