Vanilla Breeze

a

The anchor element creates hyperlinks to web pages, files, email addresses, locations within the same page, or any other URL.

Progressive Enhancement

The anchor element is the fundamental building block of the web. It works in every browser with zero CSS or JavaScript.

  • HTML-first: Links function without any styling — the browser provides default blue/purple colors and underlines
  • CSS-enhanced: Vanilla Breeze adds interactive colors, hover effects, auto-detected link-type indicators, and focus rings
  • No JavaScript required: All link functionality is native browser behavior

When to Use

  • Navigation: Links in site navigation, menus, and breadcrumbs
  • In-page links: Table of contents linking to sections
  • External resources: Linking to external sites and references
  • Downloads: Use with download attribute for downloadable files
  • Contact links: Use mailto: and tel: protocols

When NOT to Use

  • Actions: Use <button> for toggles, dialogs, form submission, or state changes
  • Dialogs: Use <button commandfor="..." command="show-modal"> via the Invokers API

Auto-Detection

Vanilla Breeze automatically detects and adds visual indicators to special link types using CSS only — no JavaScript required.

Link Type Detection Indicator
External href^="http" ↑ arrow after text
Download [download] ↓ arrow after text
Email href^="mailto" ✉ envelope before text
Phone href^="tel" ☎ phone before text
PDF href$=".pdf" PDF badge after text

Custom Link Icons

Use icon-wc inside links for custom icons. Add data-no-icon to suppress the auto-inserted indicator when using your own.

Suppressing Auto-Icons

Use data-no-icon to suppress automatic icons. Links inside <nav>, <header>, and <footer> automatically suppress icons — no attribute needed.

Variants

Use data-variant to change link appearance.

Button-Styled Links

Use class="button" on a link to give it button styling. This is for links that navigate to another page but need the visual weight of a button — hero CTAs, sign-up links, prominent calls to action.

All button variants and sizes work: .secondary, .ghost, .small, .large, and .full-width. Auto-icons are automatically suppressed on button-styled links.

Note: For actions that don't navigate (toggles, form submission, dialogs), use <button> instead.

Links Wrapping Content

When links wrap images, pictures, figures, or cards, the underline is automatically removed via the CSS :has() selector.

Context Overrides

Auto-icons are suppressed in certain contexts to keep UI clean:

Key Attributes

Attribute Description
href The URL the link points to (required for a functional link)
target Where to open the link (_blank for new tab)
rel Relationship between pages (noopener, noreferrer)
download Prompts download instead of navigation
hreflang Language of the linked document
data-variant Visual variant: muted | plain
data-no-icon Suppress auto-detected link type icons

CSS Properties

Property Value
color var(--color-interactive)
text-decoration underline
text-decoration-thickness 1px (default), 2px (hover)
text-underline-offset 0.15em
transition var(--duration-fast) var(--ease-default)

Link States

Hover

Underline thickness increases from 1px to 2px on hover.

Focus

A visible focus ring appears when navigating via keyboard (uses :focus-visible with var(--color-interactive) outline).

Visited

Vanilla Breeze deliberately does not style :visited links. This is a privacy decision — browsers restrict what CSS properties can be applied to visited links to prevent history sniffing attacks.

Accessibility

  • Descriptive link text: Avoid "click here" or "read more" — use meaningful text that describes the destination
  • Visual distinction: Links have underlines by default — color alone is not sufficient to identify links
  • Focus visibility: Links have visible focus rings for keyboard navigation
  • New tab warning: When links open in new tabs, inform users
  • Skip links: Use anchor links to create "skip to content" navigation

External Link Best Practice

For links that open in a new tab, add a visually hidden notice for screen reader users:

Related
↑