HTMLLinkElement.rel — Eigenschaft · JavaScript-Referenz

Signatur

HTMLLinkElement.rel

Beschreibung

Die Eigenschaft rel des HTMLLinkElement-Interfaces spiegelt das HTML-Attribut rel eines <link>-Elements wider. Sie enthält eine durch Leerzeichen getrennte Liste von Linktypen wie stylesheet, icon, preload, preconnect, canonical oder alternate. Diese Liste legt fest, wie der Browser mit der unter href angegebenen Ressource umgeht.

Sinnvoll ist die Eigenschaft vor allem dann, wenn man <link>-Elemente dynamisch erzeugt, z. B. um Stylesheets nachzuladen, Ressourcen per preload oder prefetch vorab anzufordern oder das Favicon zur Laufzeit auszutauschen. Außerdem lassen sich damit bestehende Links im <head> auswerten, etwa um die kanonische URL einer Seite herauszufinden.

Der Wert ist ein einfacher String. Wer einzelne Linktypen hinzufügen, entfernen oder prüfen will, ohne selbst Strings zu zerlegen, sollte HTMLLinkElement.relList verwenden. Diese Eigenschaft liefert eine DOMTokenList mit add(), remove(), contains() und supports().

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Nur beim Setzen: neue, durch Leerzeichen getrennte Liste von Linktypen, z. B. `"stylesheet"` oder `"alternate stylesheet"`.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des rel-Attributs. Fehlt das Attribut, ist es ein leerer String "".

Beispiele

Stylesheet dynamisch nachladen

const loadStylesheet = (url) => new Promise((resolve, reject) => {
  const link = document.createElement('link');
  link.rel = 'stylesheet';
  link.href = url;
  link.onload = () => resolve(link);
  link.onerror = () => reject(new Error(`Konnte ${url} nicht laden`));
  document.head.append(link);
});

const link = await loadStylesheet('/css/dark-theme.css');
console.log(link.rel);

stylesheet

Alle Link-Beziehungen im <head> auflisten

// Angenommen im <head>:
// <link rel="icon" href="/favicon.ico">
// <link rel="canonical" href="https://example.com/artikel">
const links = document.querySelectorAll('head link');
for (const link of links) {
  console.log(`${link.rel} -> ${link.href}`);
}

const canonical = document.querySelector('link[rel="canonical"]');
console.log('Kanonische URL:', canonical?.href ?? 'keine');

icon -> https://example.com/favicon.ico canonical -> https://example.com/artikel Kanonische URL: https://example.com/artikel

Ressource vorab laden, mit Feature-Prüfung

const preloadFont = (url) => {
  const link = document.createElement('link');
  // relList.supports prüft, ob der Browser den Linktyp kennt
  if (!link.relList.supports('preload')) return;
  link.rel = 'preload';
  link.as = 'font';
  link.type = 'font/woff2';
  link.crossOrigin = 'anonymous';
  link.href = url;
  document.head.append(link);
};

preloadFont('/fonts/inter.woff2');

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;
  console.log(icon.rel, icon.href);
};

setFavicon('/icons/unread.png');

icon https://example.com/icons/unread.png

// Wichtig · Fallstricke

String statt Liste: rel kann mehrere Werte enthalten, z. B. \"alternate stylesheet\". Ein Vergleich wie link.rel === 'stylesheet' schlägt dann fehl. Verwende besser link.relList.contains('stylesheet') oder im Selektor [rel~=\"stylesheet\"].
Überschreiben: Beim Setzen von rel wird der ganze Wert ersetzt. Um einen einzelnen Typ zu ergänzen, nimm relList.add().
Nachträgliche Änderung: Wird rel an einem schon eingefügten Element geändert (z. B. von preload auf stylesheet), verarbeitet der Browser den Link neu. Das nutzt man gezielt beim Muster „Preload, dann als Stylesheet anwenden“.
Groß-/Kleinschreibung: Linktypen werden ohne Beachtung der Groß-/Kleinschreibung ausgewertet. Die Eigenschaft gibt den Wert aber genau so zurück, wie er im Attribut steht.
Sicherheit: Bei Links auf fremde Ressourcen spielen crossOrigin, integrity und die Content Security Policy (style-src, font-src usw.) eine Rolle. rel allein umgeht keine CSP.
Kompatibilität: Die Eigenschaft selbst funktioniert in allen Browsern. Einzelne Linktypen wie modulepreload oder preconnect werden aber nicht überall unterstützt. Prüfe das mit relList.supports().

Siehe auch

HTMLAreaElement.rel HTMLLinkElement.href HTMLLinkElement.as HTMLLinkElement.media HTMLLinkElement.relList