Installation

Barrel

Granular

Usage

Basic Link

The default Link component renders an underlined anchor with primary color styling.

export default function Example() {
  return (
    <p>
      Read our <Link href="/docs">documentation</Link> for more details.
    </p>
  );
}

External Links

Use the Link.ExternalIcon subcomponent to indicate links that open in a new tab.

export default function Example() {
  return (
    <Link
      href="https://cloudflare.com"
      target="_blank"
      rel="noopener noreferrer"
    >
      Visit Cloudflare <Link.ExternalIcon />
    </Link>
  );
}

Framework Integration (LinkProvider)

For app-wide router integration, configure a LinkProvider at your app root. Your wrapper component receives href and is responsible for bridging to your router's API. This lets engineers use <Link href="..."> everywhere without thinking about routing internals.

// Your app's wrapper maps href to the router's navigation prop
// and handles external URLs with a plain <a>
const AppLink = forwardRef(({ href, to, ...rest }, ref) => {
  const destination = href ?? to;
  const isExternal =
    destination?.startsWith("http") &&
    new URL(destination).origin !== window.location.origin;

  if (isExternal) {
    return <a ref={ref} href={destination} {...rest} />;
  }
  return <RouterLink ref={ref} to={destination} {...rest} />;
});

// Wrap your app once
export function App() {
  return (
    <LinkProvider component={AppLink}>
      {/* All <Link href="..."> calls go through AppLink */}
      <YourApp />
    </LinkProvider>
  );
}

Composition with render prop

For exceptional cases where you need direct control over the rendered element, use the render prop. This bypasses the LinkProvider entirely — all other props (href, target, className, etc.) are merged onto the provided element automatically.

export default function Example() {
  return (
    <>
      {/* Force a specific router link (bypasses LinkProvider) */}
      <Link render={<RouterLink to="/dashboard" />} variant="inline">
        Dashboard
      </Link>

      {/* Force a plain anchor (bypasses LinkProvider) */}
      <Link render={<a />} href="https://example.com" target="_blank" rel="noopener noreferrer">
        External Site <Link.ExternalIcon />
      </Link>
    </>
  );
}

Examples

Inline in Paragraph

Links flow naturally within paragraph text with proper underline offset.

External Link with Icon

Use Link.ExternalIcon to visually indicate links that navigate away from your site.

Current Variant (Color Inheritance)

The current variant inherits color from its parent, useful for links within colored contexts like alerts.

Composition with render prop

The render prop lets you compose Link styling onto any element, enabling integration with framework routing components.

API Reference

Link Props

Extends all native anchor element attributes.

Variants

Link.ExternalIcon

SVG icon component to indicate external links. Accepts all SVG element attributes.

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

Design Guidelines

  ### When to Use Each Variant

  <ul class="ml-4 list-disc space-y-1">
    <li>
      <strong>inline</strong>: Default choice for links within body text
    </li>
    <li>
      <strong>current</strong>: Links inside alerts, banners, or other
      colored containers
    </li>
    <li>
      <strong>plain</strong>: Navigation menus, footers, or where underlines
      are distracting
    </li>
  </ul>



  ### External Link Indicators

  <ul class="ml-4 list-disc space-y-1">
    <li>Always use `Link.ExternalIcon` for links that open in new tabs</li>
    <li>
      Set `target="_blank"` and `rel="noopener noreferrer"` for security
    </li>
    <li>
      The icon provides a visual cue that users will leave the current site
    </li>
  </ul>



  ### Framework Integration

  <ul class="ml-4 list-disc space-y-1">
    <li>
      Configure a `LinkProvider` at your app root to integrate with your
      client-side router
    </li>
    <li>
      Your wrapper receives `href` and maps it to your router's
      navigation prop (e.g. React Router's `to`)
    </li>
    <li>
      The wrapper should handle external URLs by rendering a plain
      `&lt;a&gt;` instead of routing them
    </li>
    <li>
      Use the `render` prop as an escape hatch for exceptional cases
      that need direct control over the rendered element
    </li>
    <li>
      The `to` prop is deprecated — use `href` for all link destinations
    </li>
  </ul>



  ### Accessibility

  <ul class="ml-4 list-disc space-y-1">
    <li>Links are keyboard focusable by default</li>
    <li>
      The external icon has `aria-hidden="true"` - add descriptive text for
      screen readers
    </li>
    <li>Ensure sufficient color contrast for all variants</li>
    <li>Use descriptive link text (avoid "click here")</li>
  </ul>