HTMLLinkElement.href — Eigenschaft · JavaScript-Referenz

Signatur

HTMLLinkElement.href

Beschreibung

Die Eigenschaft href der Schnittstelle HTMLLinkElement spiegelt das HTML-Attribut href eines <link>-Elements wider. Sie enthält die URL der verknüpften Ressource, also etwa eines Stylesheets (rel="stylesheet"), eines Favicons (rel="icon"), einer vorab zu ladenden Datei (rel="preload") oder einer kanonischen URL (rel="canonical").

Beim Lesen liefert die Eigenschaft immer eine absolute, aufgelöste URL. Relative Angaben werden anhand der Basis-URL des Dokuments aufgelöst, also über document.baseURI bzw. ein vorhandenes <base>-Element. Den Rohwert, wie er im Markup steht, bekommst du dagegen mit getAttribute("href").

Beim Schreiben wird das Attribut aktualisiert. Bei Stylesheets und Icons lädt der Browser die neue Ressource dann sofort nach. Darauf beruhen typische Muster wie das Umschalten von Themes, dynamische Favicons (etwa Benachrichtigungszähler) oder das Nachladen von CSS zur Laufzeit.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Nur beim Setzen: neue URL (relativ oder absolut). Wird als Attribut `href` gespeichert und beim Lesen gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

string

Beschreibung

Die vollständig aufgelöste, absolute URL der verknüpften Ressource. Fehlt das Attribut, ist der Rückgabewert ein leerer String. Ist der Wert keine gültige URL, wird der Rohwert unverändert zurückgegeben.

Beispiele

Absolute URL gegenüber dem Attributwert

// Markup: <link id="main-css" rel="stylesheet" href="css/style.css">
// Seite läuft unter https://example.com/blog/
const link = document.getElementById('main-css');

console.log(link.href);                 // aufgelöste URL
console.log(link.getAttribute('href')); // Rohwert aus dem HTML

https://example.com/blog/css/style.css css/style.css

Theme umschalten (Hell/Dunkel)

// Markup: <link id="theme" rel="stylesheet" href="/themes/light.css">
const themeLink = document.querySelector('#theme');

const toggleTheme = () => {
  const isDark = themeLink.href.endsWith('/dark.css');
  themeLink.href = isDark ? '/themes/light.css' : '/themes/dark.css';
  localStorage.setItem('theme', isDark ? 'light' : 'dark');
};

document.querySelector('#theme-toggle').addEventListener('click', toggleTheme);

Stylesheet dynamisch nachladen und auf das Laden warten

const loadStylesheet = (url) => new Promise((resolve, reject) => {
  const link = document.createElement('link');
  link.rel = 'stylesheet';
  link.href = url;
  link.addEventListener('load', () => resolve(link));
  link.addEventListener('error', () => reject(new Error(`CSS konnte nicht geladen werden: ${link.href}`)));
  document.head.append(link);
});

const link = await loadStylesheet('/css/print.css');
console.log('Geladen:', link.href);

Geladen: https://example.com/css/print.css

Favicon zur Laufzeit per Data-URL tauschen

const setFaviconBadge = (count) => {
  const canvas = document.createElement('canvas');
  canvas.width = canvas.height = 32;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = '#d00';
  ctx.beginPath();
  ctx.arc(16, 16, 16, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = '#fff';
  ctx.font = 'bold 20px sans-serif';
  ctx.textAlign = 'center';
  ctx.fillText(String(count), 16, 23);

  const icon = document.querySelector('link[rel~="icon"]') ?? document.head.appendChild(
    Object.assign(document.createElement('link'), { rel: 'icon' })
  );
  icon.href = canvas.toDataURL('image/png');
};

setFaviconBadge(3);

// Wichtig · Fallstricke

Aufgelöste URL gegenüber Rohwert: link.href liefert immer die absolute URL. Wer mit relativen Pfaden vergleicht (link.href === 'style.css'), bekommt deshalb nie einen Treffer. Nimm stattdessen getAttribute('href') oder new URL(link.href).pathname.
Kein load-Event bei gleichem Wert: Setzt du dieselbe URL erneut, lädt der Browser die Datei meist nicht neu. Für ein erzwungenes Neuladen (Cache-Busting) hängst du einen Query-Parameter an, z. B. ?v=${Date.now()}.
Flackern beim Theme-Wechsel: Während das neue Stylesheet lädt, gilt das alte nicht mehr. Das kann einen kurzen Moment ohne Styles (FOUC) verursachen. Abhilfe: Das neue <link> zusätzlich einfügen und das alte erst nach dessen load-Event entfernen.
Sicherheit: Übernimm keine ungeprüften Benutzereingaben als href. Ein fremdes Stylesheet kann per CSS Daten abgreifen (etwa über Attributselektoren mit Hintergrundbildern) oder die Seite optisch manipulieren. Beschränke die Quellen per Content Security Policy (style-src, img-src). Bei Ressourcen von fremden Servern gehören integrity und crossOrigin dazu.
Kompatibilität: Wird von allen Browsern seit Jahren unterstützt. Das Nachladen dynamischer Favicons funktioniert in Safari nur eingeschränkt.

Siehe auch

HTMLLinkElement HTMLLinkElement.rel HTMLLinkElement.crossOrigin HTMLAnchorElement.href Element.getAttribute()