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
downloadattribute for downloadable files - Contact links: Use
mailto:andtel: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 |
href^="mailto" |
✉ envelope before text | |
| Phone | href^="tel" |
☎ phone before text |
href$=".pdf" |
PDF badge after text |
<a href="https://example.com">Example.com</a><a href="/files/report.pdf" download>Download the PDF</a>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.
<a href="/files/report.pdf" download data-no-icon> <icon-wc name="file-text" size="xs"></icon-wc> Annual Report (PDF)</a> <a href="https://github.com/example" data-no-icon> <icon-wc name="github" size="xs"></icon-wc> View on GitHub</a>Suppressing Auto-Icons
Use data-no-icon to suppress automatic icons. Links inside <nav>, <header>, and <footer> automatically suppress icons — no attribute needed.
<a href="https://example.com" data-no-icon>Example.com</a>Variants
Use data-variant to change link appearance.
<a href="#">default link</a><a href="#" data-variant="muted">muted link</a><a href="#" data-variant="plain">plain link</a>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.
<a href="/get-started/" class="button">Get Started</a><a href="/docs/" class="button secondary">Documentation</a><a href="/learn/" class="button ghost">Learn More</a><a href="#" class="button small">Small</a><a href="#" class="button">Default</a><a href="#" class="button large">Large</a>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.
<a href="#"> <img src="image.jpg" alt="..." /></a><a href="#"> <layout-card data-padding="m"> <p>Click this entire card</p> </layout-card></a>Context Overrides
Auto-icons are suppressed in certain contexts to keep UI clean:
/* Links in nav/header/footer suppress auto-icons */nav a[href^="http"]::after { content: none; }header a[href^="http"]::after { content: none; }footer a[href^="http"]::after { content: none; } /* Icon-only links suppress indicators */a:has(> icon-wc:only-child)::after { content: none; } /* Button-styled links suppress auto-icons */a.button[href^="http"]::after { content: none; }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:
<a href="https://example.com" target="_blank" rel="noopener noreferrer"> Example.com <span class="visually-hidden">(opens in new tab)</span></a>Related
<button>— For actions that don't navigate<nav>— For wrapping navigation links (suppresses auto-icons)<foot-notes>— For footnote reference links<icon-wc>— Lucide icons inside links<heading-links>— Auto-generates anchor links for headings