Link

Refer to the v3 Link documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Key Changes

1. Component Structure

v2: Single component with icon props
v3: Compound component: Link.Icon for icons

2. Prop Changes

v2 Prop	v3 Location	Notes
`showAnchorIcon`, `anchorIcon`	-	Use `Link.Icon` component with children
`isExternal`	-	Use `target="_blank"` and `rel="noopener noreferrer"`
`size`, `color`, `isBlock`	-	Removed (use Tailwind CSS)
`disableAnimation`	-	Removed
`underline`	-	Removed (use Tailwind `underline`, etc.)

3. New Props

onPress - Event handler fired when the link is activated (via click or keyboard). Accepts a (e: PressEvent) => void callback.

Structure Changes

In v2, Link component usage:

import { Link } from "@heroui/react";

export default function App() {
  return <Link href="#">Default Link</Link>;
}

In v3, Link component usage remains the same for basic cases:

import { Link } from "@heroui/react";

export default function App() {
  return <Link href="#">Default Link</Link>;
}

Migration Examples

With Icons

{/* Default icon */}
<Link showAnchorIcon href="#">
  External Link
</Link>

{/* Custom icon */}
<Link
  showAnchorIcon
  anchorIcon={<CustomIcon />}
  href="#"
>
  Custom Icon
</Link>

{/* Default icon */}
<Link href="#">
  External Link
  <Link.Icon />
</Link>

{/* Custom icon */}
<Link href="#">
  Custom Icon
  <Link.Icon>
    <CustomIcon />
  </Link.Icon>
</Link>

External Link

<Link isExternal href="https://example.com">
  External Link
</Link>

<Link
  href="https://example.com"
  target="_blank"
  rel="noopener noreferrer"
>
  External Link
  <Link.Icon />
</Link>

Underline and offset (v3: use Tailwind)

<Link href="#" underline="hover">
  Hover to underline
</Link>

<Link href="#" className="hover:underline">
  Hover to underline
</Link>
<Link href="#" className="underline underline-offset-2">
  Underline with offset
</Link>

With routing libraries

import NextLink from "next/link";
import { Link } from "@heroui/react";

<Link as={NextLink} href="/about">
  About
</Link>

import NextLink from "next/link";
import { Link } from "@heroui/react";

{/* Style your router link with the same classes as Link; add an icon if needed */}
<NextLink href="/about" className="link hover:underline">
  About
</NextLink>

Component Anatomy

The v3 Link follows this structure:

Link (Root)
  ├── Link content (text)
  └── Link.Icon (optional)

Summary

Icon Handling: showAnchorIcon and anchorIcon props replaced with Link.Icon component
External Links: isExternal prop removed - handle manually with target and rel
Size Prop Removed: Use Tailwind CSS classes (text-sm, text-base, text-lg)
Color Prop Removed: Use Tailwind CSS classes (text-primary, text-danger, etc.)
Block Prop Removed: Use Tailwind CSS classes (block, hover:bg-surface)
Underline: No longer a prop; use Tailwind (underline, hover:underline, no-underline, underline-offset-1, etc.)
Routing: v3 Link does not support as or asChild; use your router's Link with Tailwind classes (e.g. link, link__icon) for consistent styling
Animation Removed: disableAnimation prop removed
onPress Handler: New onPress prop available for handling link activation events (click or keyboard)

On this page