Link

An inline text link — for a link that should look like a button, use Button with href instead.

Last updated

Default linkHover underline
Show code
<Link href="#">Default link</Link>
<Link href="#" underline="hover">Hover underline</Link>

Add

npx @ava-ui/apogee add link

No Apogee dependencies.

Usage

---
import Link from '@/components/apogee/Link/Link.astro'
---
<Link href="/docs">Read the docs</Link>

API

@composable — exposed to Content Editors in AVA. Any other native <a> attribute (e.g. download, hreflang) passes through.

Prop Type Default Description
href string — Required. Link destination.
color 'primary' | 'neutral' | 'critical' | 'positive' | 'warning' | 'inherit' 'primary' Text colour; inherit takes the surrounding colour.
underline 'always' | 'hover' | 'none' 'always' Underline behaviour.
disabled boolean false No href, aria-disabled, dimmed.
external boolean false Opens in a new tab (target="_blank") with rel="noopener noreferrer".
class string — Extra classes, merged last.

Variants

Every underline value:

Always underlinedUnderline on hoverNever underlined
Show code
<Link href="#" underline="always">Always underlined</Link>
<Link href="#" underline="hover">Underline on hover</Link>
<Link href="#" underline="none">Never underlined</Link>

Colours

Every color; inherit takes the colour of the text around it.

PrimaryNeutralCriticalPositiveWarningInside critical text, inherit matches it.
Show code
<Link href="#" color="primary">Primary</Link>
<Link href="#" color="neutral">Neutral</Link>
<Link href="#" color="critical">Critical</Link>
<Link href="#" color="positive">Positive</Link>
<Link href="#" color="warning">Warning</Link>
<span class="text-critical">Inside critical text, <Link href="#" color="inherit">inherit</Link> matches it.</span>

States

  • Hover — colour shifts to --background-primary-highlighted; underline="hover" reveals its underline.
  • Focus — a visible focus-visible ring (--border-primary).

Examples

With icons in the start / end slots (sized to the text):

Email usDocs
Show code
<Link href="#"><Mail slot="start" /> Email us</Link>
<Link href="#" external>Docs<ExternalLink slot="end" /></Link>

Semantic colours and a disabled link:

DeleteApprovedPendingUnavailable
Show code
<Link href="#" color="critical">Delete</Link>
<Link href="#" color="positive">Approved</Link>
<Link href="#" color="warning">Pending</Link>
<Link href="#" disabled>Unavailable</Link>

External link, with a trailing icon as the visual cue:

Visit example.com
Show code
<Link href="https://example.com" external underline="hover">Visit example.com <ExternalLink class="inline size-3.5" /></Link>

Accessibility

  • Real <a href> — full keyboard and assistive-tech support; reachable via Tab, activates with Enter.
  • Focus ring always visible on keyboard focus.
  • external sets rel="noopener noreferrer" (the new tab can’t access window.opener) — pair it with a visual cue (e.g. an icon) so users aren’t surprised it left the site.
  • No JS.

Tokens

Token Used for
--foreground-primary Link colour
--outline-color-focus Focus ring

Do / Don’t

  • Do use Link for inline, in-sentence navigation; use Button with href for a link that should look like a call-to-action.
  • Do set external (and ideally show an icon) for links that leave the site.
  • Don’t rely on colour alone to distinguish a link from surrounding text — keep underline="always" (the default) for body copy.
  • Don’t use underline="none" outside nav/UI chrome where the link is already visually distinct (e.g. a menu item).

Content

  • Link text describes the destination (“Read the pricing guide”), never “click here” or a bare URL.
  • Keep it concise — a few words, not a full sentence.

Related

ActionableThe bare interactive primitive. A button, link or focusable div with the focus ring and disabled handling, nothing else.
ButtonTriggers an action. Renders a <button>, or an <a> when href is set. Hue, fill and height are three separate props.
NavLinkA navigation link that auto-detects and styles the current route, with prefix matching, external links and a collapsible NavGroup.