Link

By continuing you agree to our Terms of Service and Privacy Policy.

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

export default function LinkDemo() {
  return (
    <p className="max-w-sm text-muted-foreground text-sm leading-relaxed">
      By continuing you agree to our <Link href="#">Terms of Service</Link> and{" "}
      <Link href="#">Privacy Policy</Link>.
    </p>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/link

The CLI installs dependencies and any other components this one uses.

Usage

tsx

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

tsx

<Link href="/pricing">Pricing</Link>

When to use

Link — navigation: to another page, a section of this page, a file download or an email address.
Button — an action that doesn't navigate (submit, open a dialog, delete). If it needs to look like a link, use <Button variant="link">.
A button-styled link — navigation that should look like a button. Apply buttonVariants to a React Aria or Next.js link.
Breadcrumbs and Pagination — structured navigation, built on the same link.

Anatomy

tsx

<Link href="…">   {/* <a>, or <span role="link"> without href */}
  <Icon />        {/* optional, size it yourself */}
  Label
  {/* ↗ arrow, added when isExternal */}
</Link>

Part	Renders	Notes
`Link`	`<a>` or `<span role="link">`	An `<a>` when `href` is set and the link isn't disabled; otherwise a focusable `<span>` with `role="link"`. Inline flex with a small gap.
External arrow	`<svg>`	Appended after the children when `isExternal`. `aria-hidden`.

default is the brand-colored, medium-weight link for calls to action and standalone links. subtle is muted until hovered, for footers, metadata and dense navigation. underline keeps the text color with a soft underline, for links inside body copy where color alone isn't enough.

Default Subtle Underline

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

export default function LinkVariants() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm">
      <Link href="#">Default</Link>
      <Link href="#" variant="subtle">
        Subtle
      </Link>
      <Link href="#" variant="underline">
        Underline
      </Link>
    </div>
  );
}

External

isExternal sets target="_blank" and rel="noreferrer" and adds an arrow icon. Pass your own target or rel to override them.

Built on React Aria and styled with Tailwind CSS.

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

export default function LinkExternal() {
  return (
    <p className="max-w-sm text-muted-foreground text-sm leading-relaxed">
      Built on{" "}
      <Link href="https://react-spectrum.adobe.com/react-aria/" isExternal>
        React Aria
      </Link>{" "}
      and styled with{" "}
      <Link href="https://tailwindcss.com" isExternal variant="underline">
        Tailwind CSS
      </Link>
      .
    </p>
  );
}

Disabled

isDisabled renders a <span> instead of an <a>, removes it from the tab order and dims it. Prefer hiding links that can never be followed; disable ones that will become available.

Download invoiceView receipt

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

export default function LinkDisabled() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm">
      <Link href="#" isDisabled>
        Download invoice
      </Link>
      <Link href="#" variant="subtle" isDisabled>
        View receipt
      </Link>
    </div>
  );
}

With icon

Children are laid out in an inline flex row, so icons line up with the text. Icons aren't sized automatically; add size-4 (or size-3.5 for small text) and widen the gap with gap-1.5. download and mailto: links work as on a native <a>.

Back to invoices Download PDF support@acme.dev

import { ArrowLeftIcon, DownloadIcon, MailIcon } from "lucide-react";
import { Link } from "@/components/ui/link";

export default function LinkWithIcon() {
  return (
    <div className="flex flex-col items-start gap-3 text-sm">
      <Link href="#" variant="subtle" className="gap-1.5">
        <ArrowLeftIcon className="size-4" /> Back to invoices
      </Link>
      <Link href="#" download="invoice-2026-09.pdf" className="gap-1.5">
        <DownloadIcon className="size-4" /> Download PDF
      </Link>
      <Link href="mailto:support@acme.dev" className="gap-1.5">
        <MailIcon className="size-4" /> support@acme.dev
      </Link>
    </div>
  );
}

Current page

Set aria-current="page" on the link for the page you're on. React Aria exposes it as data-current, so you can style it with data-current:….

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

const pages = ["Overview", "Changelog", "Pricing", "Docs"];

export default function LinkCurrent() {
  return (
    <nav aria-label="Product">
      <ul className="flex flex-wrap items-center gap-5 text-sm">
        {pages.map((page) => (
          <li key={page}>
            <Link
              href="#"
              variant="subtle"
              aria-current={page === "Pricing" ? "page" : undefined}
              className="data-current:font-medium data-current:text-foreground"
            >
              {page}
            </Link>
          </li>
        ))}
      </ul>
    </nav>
  );
}

With a router

Wrap your app in React Aria's RouterProvider and every Link (plus breadcrumbs, tabs, menu items and other link-capable components) navigates with your client-side router. Modifier clicks, target="_blank" and cross-origin links still use the browser.

app/providers.tsxtsx

"use client";

import { useRouter } from "next/navigation";
import { RouterProvider } from "react-aria-components";

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}

Pass router-specific options with routerOptions; they're forwarded as the second argument to navigate. Register their type once so they're type-checked:

app/providers.tsxtsx

declare module "react-aria-components" {
  interface RouterConfig {
    routerOptions: NonNullable<
      Parameters<ReturnType<typeof useRouter>["push"]>[1]
    >;
  }
}

tsx

<Link href="/settings" routerOptions={{ scroll: false }}>
  Settings
</Link>

To use Next.js prefetching, style next/link with linkVariants instead. Hover and focus styles in linkVariants rely on React Aria's data-hovered and data-focus-visible attributes, so add hover: and focus-visible: classes when using it on a plain element.

Recipes

Columns of subtle links grouped in labelled <nav> elements, with legal links and an external link in the bottom row.

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

const columns = [
  {
    title: "Product",
    links: ["Features", "Integrations", "Pricing", "Changelog"],
  },
  { title: "Company", links: ["About", "Customers", "Careers", "Press"] },
  {
    title: "Resources",
    links: ["Documentation", "Guides", "API status", "Community"],
  },
];

export default function LinkRecipeFooter() {
  return (
    <footer className="grid w-full max-w-2xl gap-8 rounded-lg border bg-card p-6">
      <div className="grid grid-cols-2 gap-6 sm:grid-cols-3">
        {columns.map((col) => (
          <nav
            key={col.title}
            aria-label={col.title}
            className="grid content-start gap-3"
          >
            <h3 className="font-medium text-sm">{col.title}</h3>
            <ul className="grid gap-2 text-sm">
              {col.links.map((label) => (
                <li key={label}>
                  <Link href="#" variant="subtle">
                    {label}
                  </Link>
                </li>
              ))}
            </ul>
          </nav>
        ))}
      </div>
      <div className="flex flex-wrap items-center justify-between gap-3 border-t pt-4 text-muted-foreground text-xs">
        <span>© 2026 Acme Inc.</span>
        <div className="flex gap-4">
          <Link href="#" variant="subtle">
            Privacy
          </Link>
          <Link href="#" variant="subtle">
            Terms
          </Link>
          <Link href="https://github.com" variant="subtle" isExternal>
            GitHub
          </Link>
        </div>
      </div>
    </footer>
  );
}

Inline links around a form: "Forgot password?" aligned under the field, a sign-up prompt, and underline links in the legal text.

Welcome back. Enter your details to continue.

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Link } from "@/components/ui/link";
import { TextField } from "@/components/ui/text-field";

export default function LinkRecipeSignIn() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Sign in</CardTitle>
        <CardDescription>
          Welcome back. Enter your details to continue.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <Form className="grid gap-4" onSubmit={(e) => e.preventDefault()}>
          <TextField label="Email" type="email" placeholder="you@company.com" />
          <div className="grid gap-1.5">
            <TextField label="Password" type="password" />
            <Link href="#" className="justify-self-end text-xs">
              Forgot password?
            </Link>
          </div>
          <Button type="submit" className="w-full">
            Sign in
          </Button>
          <p className="text-center text-muted-foreground text-xs">
            New to Acme? <Link href="#">Create an account</Link>
          </p>
          <p className="text-center text-muted-foreground text-xs leading-relaxed">
            By continuing you agree to the{" "}
            <Link href="#" variant="underline">
              Terms
            </Link>{" "}
            and{" "}
            <Link href="#" variant="underline">
              Privacy Policy
            </Link>
            .
          </p>
        </Form>
      </CardContent>
    </Card>
  );
}

Accessibility

With href, renders a native <a>, so browser features like "open in new tab", copy link address and the status-bar preview work, and screen readers list it as a link.
Without href (or when disabled), renders a <span role="link"> that's focusable and responds to Enter. Prefer a Button for actions.
isDisabled sets aria-disabled and removes the link from the tab order.
The focus ring appears only for keyboard focus (data-focus-visible).
The external arrow is aria-hidden. If opening a new tab could surprise users, say so in the text or add an sr-only "(opens in a new tab)".
Don't rely on color alone to identify links in body text; use the underline variant there.

Keyboard

Key	Action
`Tab`	Moves focus to the link
`Enter`	Follows the link

Styling

Data attributes

Attribute	Present when
`data-hovered`	Hovered with a mouse or pen
`data-pressed`	Being pressed
`data-focused` / `data-focus-visible`	Focused / focused with the keyboard
`data-current`	`aria-current` is set
`data-disabled`	`isDisabled` is true
`data-slot="link"`	Always

Render props

className and children accept a function of the link's state:

tsx

<Link href="/inbox" className={({ isCurrent }) => (isCurrent ? "font-semibold" : "")}>
  {({ isHovered }) => (isHovered ? "Open inbox →" : "Inbox")}
</Link>

`linkVariants`

The tailwind-variants function behind the component.

tsx

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

linkVariants({ variant: "subtle", className: "text-xs" });

API Reference

Link

Prop

Type

Also accepts every prop of React Aria's Link.

linkVariants

Prop

Type

Button — for actions, and buttonVariants for button-styled links.
Breadcrumbs — a trail of links to parent pages.
Pagination — links between pages of results.
Sidebar — navigation links for an app.

Link

Installation

Usage

When to use

Anatomy

Examples

Variants

External

Disabled

With icon

Current page

With a router

Recipes

Site footer

Accessibility

Keyboard

Styling

Data attributes

Render props

`linkVariants`

API Reference

Link

linkVariants