HTMLLinkElement.relList — Eigenschaft · JavaScript-Referenz

Signatur

HTMLLinkElement.relList

Beschreibung

Die Eigenschaft relList eines HTMLLinkElement gibt eine dynamische DOMTokenList zurück. Sie enthält die einzelnen Link-Typen aus dem rel-Attribut, z. B. stylesheet, preload, icon oder alternate. Diese Typen beschreiben, in welcher Beziehung die verlinkte Ressource zum aktuellen Dokument steht.

Im Unterschied zur String-Eigenschaft rel musst du die Werte nicht selbst an Leerzeichen trennen. Mit den Methoden add(), remove(), toggle(), replace() und contains() kannst du einzelne Tokens gezielt lesen und ändern. Jede Änderung wird sofort in das rel-Attribut zurückgeschrieben, und umgekehrt spiegelt die Liste jede Änderung am Attribut sofort wider.

Besonders nützlich ist relList.supports(). Damit prüfst du per Feature-Erkennung, ob der Browser einen bestimmten Link-Typ unterstützt, etwa preload, modulepreload oder prefetch. Erst danach fügst du ein passendes <link> dynamisch ein.

„Schreibgeschützt“ heißt hier nur, dass du der Eigenschaft kein neues Objekt zuweisen kannst. Den Inhalt der Liste kannst du trotzdem ändern. Weist du relList einen String zu, leiten die meisten Browser ihn an das rel-Attribut weiter ([PutForwards=value]).

Rückgabewert

Typ

DOMTokenList

Beschreibung

Eine dynamische Liste der Link-Typen aus dem rel-Attribut. Ist kein rel-Attribut gesetzt, ist die Liste leer (length === 0).

Beispiele

Link-Typen eines Elements auslesen

const link = document.createElement('link');
link.rel = 'preload stylesheet';

// Tokens einzeln durchlaufen
for (const type of link.relList) {
  console.log(type);
}
console.log(link.relList.length);
console.log(link.relList.contains('preload'));

preload stylesheet 2 true

Feature-Erkennung mit supports() vor dem Preload

const preloadScript = (url) => {
  const link = document.createElement('link');
  if (link.relList.supports('modulepreload')) {
    link.rel = 'modulepreload';
  } else if (link.relList.supports('preload')) {
    link.rel = 'preload';
    link.as = 'script';
  } else {
    return false; // kein Preload möglich
  }
  link.href = url;
  document.head.append(link);
  return true;
};

console.log(preloadScript('/js/app.mjs'));

true

Alternatives Stylesheet per Token umschalten

// <link rel="stylesheet" href="dark.css" title="Dunkel" id="dark">
const dark = document.createElement('link');
dark.rel = 'stylesheet';
dark.href = 'dark.css';
dark.title = 'Dunkel';
document.head.append(dark);

// Als alternatives Stylesheet markieren
dark.relList.add('alternate');
console.log(dark.getAttribute('rel'));

// Wieder zum Standard-Stylesheet machen
dark.relList.remove('alternate');
console.log(dark.rel);

stylesheet alternate stylesheet

Token ersetzen: prefetch wird zu preload

const link = document.createElement('link');
link.rel = 'prefetch';
link.href = '/fonts/inter.woff2';

const replaced = link.relList.replace('prefetch', 'preload');
link.as = 'font';
link.crossOrigin = 'anonymous';

console.log(replaced, link.rel);

true preload

// Wichtig · Fallstricke

Browser-Kompatibilität: Wird in allen modernen Browsern unterstützt (Chrome 50+, Firefox 30+, Safari 9+, Edge 17+). Der Internet Explorer kennt relList nicht. Wer ihn noch unterstützen muss, prüft vorher mit 'relList' in link.
supports() gibt es in Firefox erst ab Version 49 und in Safari etwas später. Rufe die Methode deshalb defensiv auf: link.relList?.supports?.('preload').
Die Liste ist dynamisch: Eine gespeicherte Referenz zeigt immer den aktuellen Zustand des rel-Attributs. Wer einen festen Stand braucht, kopiert die Werte mit [...link.relList].
Tokens werden ohne Beachtung der Groß-/Kleinschreibung ausgewertet, contains() vergleicht aber exakt. rel="StyleSheet" funktioniert also als Stylesheet, doch contains('stylesheet') liefert false.
add() und replace() werfen einen SyntaxError bei leeren Strings und einen InvalidCharacterError, wenn das Token Leerzeichen enthält.
Ändert man rel an einem bereits eingefügten Link, kann das Ressourcen neu laden oder entfernen (z. B. wird ein Stylesheet deaktiviert). Das wirkt sich auf die Performance und auf Layout-Verschiebungen aus.

Siehe auch

HTMLLinkElement HTMLLinkElement.rel DOMTokenList DOMTokenList.prototype.supports() HTMLAnchorElement.relList Element.classList HTMLFormElement.relList