HTMLLinkElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLLinkElement extends HTMLElement

Beschreibung

Das Interface HTMLLinkElement steht für das HTML-Element <link>. Es beschreibt die Beziehung zwischen dem aktuellen Dokument und einer externen Ressource, etwa einem Stylesheet (rel="stylesheet"), einem Favicon (rel="icon"), einer kanonischen URL (rel="canonical") oder einem Ressourcen-Hinweis wie preload, prefetch und preconnect. Nicht zu verwechseln ist es mit HTMLAnchorElement (<a>), das anklickbare Hyperlinks im Seiteninhalt darstellt.

Zu den wichtigsten Eigenschaften gehören:

href: URL der verknüpften Ressource
rel / relList: Art der Beziehung, als String bzw. DOMTokenList
as: Ressourcentyp bei preload (z. B. "style", "script", "font")
media: Media Query, für die die Ressource gilt
type, hreflang, crossOrigin, integrity, referrerPolicy, fetchPriority
disabled: deaktiviert ein Stylesheet
sheet: das zugehörige CSSStyleSheet, sobald ein Stylesheet geladen ist (sonst null)
sizes: DOMTokenList mit Icon-Größen

Typische Einsatzfälle sind das dynamische Nachladen von CSS (z. B. für Themes), das Austauschen des Favicons zur Laufzeit und gezielte Performance-Optimierung mit Preload-Hinweisen. Das Element löst die Ereignisse load und error aus. So lässt sich feststellen, ob eine Ressource erfolgreich geladen wurde.

Rückgabewert

Typ

HTMLLinkElement

Beschreibung

Instanzen entstehen über document.createElement("link") oder durch Abfragen vorhandener Elemente, z. B. mit document.querySelector("link[rel=stylesheet]").

Beispiele

Stylesheet dynamisch laden (mit Promise)

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: ${url}`)));
  document.head.append(link);
});

try {
  const link = await loadStylesheet('/css/dark-theme.css');
  console.log('Geladen, Regeln:', link.sheet.cssRules.length);
} catch (err) {
  console.error(err.message);
}

Geladen, Regeln: 42

Favicon zur Laufzeit austauschen

const setFavicon = (url) => {
  let icon = document.querySelector('link[rel~="icon"]');
  if (!icon) {
    icon = document.createElement('link');
    icon.rel = 'icon';
    document.head.append(icon);
  }
  icon.href = url;
};

// z. B. bei ungelesenen Nachrichten
setFavicon('/img/favicon-notification.png');

Schrift per Preload vorladen

const preload = document.createElement('link');
preload.rel = 'preload';
preload.as = 'font';
preload.type = 'font/woff2';
preload.href = '/fonts/inter.woff2';
preload.crossOrigin = 'anonymous'; // bei Schriften Pflicht
document.head.append(preload);

console.log(preload.relList.supports('preload'));

true

Theme-Stylesheet ein- und ausschalten

const darkTheme = document.querySelector('link#dark-theme');

document.querySelector('#toggle').addEventListener('click', () => {
  darkTheme.disabled = !darkTheme.disabled;
  console.log('Dark-Theme aktiv:', !darkTheme.disabled);
});

Dark-Theme aktiv: true

// Wichtig · Fallstricke

sheet und CORS: Ein Zugriff auf link.sheet.cssRules bei Stylesheets von fremden Ursprüngen wirft einen SecurityError, wenn sie nicht mit crossOrigin und passenden CORS-Headern geladen wurden.
Kein load-Ereignis bei jedem rel: Ob load/error ausgelöst werden, hängt vom Browser und vom rel-Wert ab (bei icon oder canonical etwa nicht zuverlässig). Registriere Listener vor dem Einfügen in das DOM.
Preload: Ohne gültiges as wird die Ressource ignoriert oder doppelt geladen. Bei Schriften ist crossOrigin nötig, auch wenn sie vom selben Ursprung kommen. Ungenutzte Preloads erzeugen Konsolenwarnungen.
Sicherheit: Für CDN-Ressourcen empfiehlt sich integrity (Subresource Integrity). Dynamisch gesetzte href-Werte unterliegen der Content Security Policy (style-src, font-src usw.). Nicht vertrauenswürdige URLs solltest du nie ungeprüft übernehmen, da fremdes CSS Daten abgreifen kann (CSS-Injection).
disabled funktioniert nur zuverlässig bei Stylesheets. Das HTML-Attribut disabled ist erst seit einigen Jahren in allen gängigen Browsern einheitlich umgesetzt.
fetchPriority und blocking sind neuere Eigenschaften und werden nicht in allen Browsern unterstützt. Prüfe die Unterstützung vorher, z. B. mit 'fetchPriority' in HTMLLinkElement.prototype.

Siehe auch

HTMLMenuElement HTMLLIElement HTMLDListElement HTMLDivElement HTMLFontElement