Link | HeroUI v3 (Previously NextUI) - The design system you don't have to build

Import

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

Usage

Call to actionCall to actionHeroUI

"use client";

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

export function LinkBasic() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Link.Root href="#">
        Call to action
        <Link.Icon />
      </Link.Root>
      <Link.Root isDisabled href="#">
        Call to action
        <Link.Icon />
      </Link.Root>
      <Link.Root
        className="border-default bg-default-100 text-foreground hover:bg-default-200 inline-flex items-center gap-2 rounded-full border px-3 py-1 text-sm font-medium transition"
        href="https://heroui.com"
        rel="noopener noreferrer"
        target="_blank"
      >
        HeroUI
        <Link.Icon className="h-3 w-3" />
      </Link.Root>
    </div>
  );
}

Anatomy

Import the Link component and access all parts using dot notation.

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

export default () => (
  <Link.Root href="#">
    Call to action
    <Link.Icon />
  </Link.Root>
);

Custom Icon

External link Inline SVG icon

"use client";

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

import {LinkIcon} from "@/icons/link";

export function LinkCustomIcon() {
  return (
    <div className="flex flex-col gap-3">
      <Link.Root href="#">
        External link
        <Link.Icon>
          <LinkIcon className="h-3.5 w-3.5" />
        </Link.Icon>
      </Link.Root>
      <Link.Root className="gap-1" href="#">
        <Link.Icon>
          <svg aria-hidden="true" className="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
            <path d="M10 2a8 8 0 1 1-8 8 8.01 8.01 0 0 1 8-8Zm.75 4.75a.75.75 0 1 0-1.5 0v4.5a.75.75 0 0 0 1.5 0Zm0 6a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Z" />
          </svg>
        </Link.Icon>
        Inline SVG icon
      </Link.Root>
    </div>
  );
}

Icon Placement

Icon at end (default)Icon at start

"use client";

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

export function LinkIconPlacement() {
  return (
    <div className="flex flex-col gap-3">
      <Link.Root href="#">
        Icon at end (default)
        <Link.Icon />
      </Link.Root>
      <Link.Root className="gap-1" href="#">
        <Link.Icon />
        Icon at start
      </Link.Root>
    </div>
  );
}

Underline Variants

Control the underline behavior with the underline prop:

Component demo "link-underline-variants" not found. Make sure the demo is registered in the demos index.

underline="hover" (default) - Animated underline appears on hover
underline="always" - Underline always visible (50% opacity, 100% on hover)
underline="none" - No underline

Underline Offset

Adjust the spacing between text and underline with the underlineOffset prop:

Component demo "link-underline-offset" not found. Make sure the demo is registered in the demos index.

underlineOffset={1} (default) - No space
underlineOffset={2} - 2px spacing
underlineOffset={3} - 4px spacing

Using with Routing Libraries

Use the asChild prop to compose Link with framework-specific links like Next.js:

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

export default function Demo() {
  return (
    <Link.Root asChild underline="hover">
      <NextLink href="/about">
        About Page
        <Link.Icon />
      </NextLink>
    </Link.Root>
  );
}

Direct Class Application

Since HeroUI uses BEM classes, you can apply Link styles directly to any link element without using asChild:

import NextLink from 'next/link';

// Apply classes directly
export default function Demo() {
  return (
    <NextLink href="/about" className="link link--underline-hover link--offset-1">
      About Page
    </NextLink>
  );
}

// Or with a native anchor
export default function NativeLink() {
  return (
    <a href="/about" className="link link--underline-always link--offset-2">
      About Page
    </a>
  );
}

Available BEM classes:

Base: link
Underline: link--underline-none, link--underline-hover, link--underline-always
Offset: link--offset-1, link--offset-2, link--offset-3

Styling

Passing Tailwind CSS classes

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

function CustomLink() {
  return (
    <Link.Root
      href="#"
      className="text-lg font-bold text-accent hover:text-accent/80"
    >
      Custom styled link
    </Link.Root>
  );
}

Customizing the component classes

To customize the Link component classes, you can use the @layer components directive.
Learn more.

@layer components {
  .link {
    @apply font-semibold no-underline hover:underline;
  }
}

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Link component uses these CSS classes (View source styles):

Base Classes

.link - Base link styles

Underline Variants

.link--underline-none - No underline
.link--underline-hover - Animated underline on hover (default)
.link--underline-always - Always visible underline

Underline Offset

.link--offset-1 - No spacing (default)
.link--offset-2 - 2px spacing
.link--offset-3 - 4px spacing

Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

Focus: :focus-visible or [data-focus-visible="true"]
Disabled: :disabled or [aria-disabled="true"]

API Reference

Link.Root Props

Prop	Type	Default	Description
`href`	`string`	-	Destination URL for the anchor
`target`	`string`	`"_self"`	Controls where to open the linked document
`rel`	`string`	-	Relationship between the current and linked documents
`download`	`boolean \| string`	-	Prompts file download instead of navigation
`underline`	`"none" \| "hover" \| "always"`	`"hover"`	Controls underline visibility and behavior
`underlineOffset`	`1 \| 2 \| 3`	`1`	Spacing between text and underline
`asChild`	`boolean`	`false`	Merge props with child element (useful for routing libraries)
`isDisabled`	`boolean`	`false`	Disables pointer and keyboard interaction
`className`	`string`	-	Custom classes merged with the default styles
`children`	`React.ReactNode`	-	Content rendered inside the link
`onPress`	`(e: PressEvent) => void`	-	Fired when the link is activated
`autoFocus`	`boolean`	-	Whether the element should receive focus on render

Link.Icon Props

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Merge props with child element
`children`	`React.ReactNode`	-	Custom icon element; defaults to the built-in arrow icon when omitted
`className`	`string`	-	Additional CSS classes

LinkUpdated

Import

Usage

Anatomy

Custom Icon

Icon Placement

Underline Variants

Underline Offset

Using with Routing Libraries

Direct Class Application

Styling

Passing Tailwind CSS classes

Customizing the component classes

CSS Classes

Base Classes

Underline Variants

Underline Offset

Interactive States

API Reference

Link.Root Props

Link.Icon Props

On this page