HTMLAnchorElement.hash — Eigenschaft · JavaScript-Referenz

Signatur

HTMLAnchorElement.hash

Beschreibung

Die Eigenschaft hash des HTMLAnchorElement-Interfaces gibt einen String zurück, der aus einem # und dem Fragmentbezeichner der im href-Attribut hinterlegten URL besteht, zum Beispiel "#kapitel-2". Hat die URL kein Fragment oder nur ein leeres (# ohne Inhalt), ist der Wert ein leerer String "".

Die Eigenschaft ist lesbar und schreibbar. Beim Schreiben wird das href-Attribut des Elements direkt angepasst. Ein führendes # im zugewiesenen Wert ist optional; der Browser ergänzt es bei Bedarf. Sonderzeichen werden nach den Regeln des URL-Standards prozentkodiert.

Typische Einsatzzwecke sind In-Page-Navigation (Sprungmarken, Inhaltsverzeichnisse), das Erkennen von Links auf Abschnitte der aktuellen Seite, Single-Page-Apps mit Hash-Routing sowie das gezielte Umschreiben von Links, ohne den Rest der URL parsen zu müssen. Die Eigenschaft stammt aus dem Mixin HTMLHyperlinkElementUtils und verhält sich genauso wie URL.prototype.hash bzw. location.hash.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: neuer Fragmentbezeichner, mit oder ohne führendes `#`. Ein leerer String entfernt das Fragment.

Rückgabewert

Typ

string

Beschreibung

Das Fragment inklusive führendem # (z. B. "#top") oder "", wenn kein bzw. ein leeres Fragment vorhanden ist.

Beispiele

Fragment eines Links auslesen

const link = document.createElement('a');
link.href = 'https://example.com/docs/api.html?lang=de#rueckgabewert';

console.log(link.hash);

// Ohne Fragment
link.href = 'https://example.com/docs/api.html';
console.log(JSON.stringify(link.hash));

#rueckgabewert ""

Fragment setzen – href wird automatisch angepasst

const link = document.createElement('a');
link.href = 'https://example.com/handbuch.html?v=3';

link.hash = 'installation'; // '#' wird ergänzt
console.log(link.href);

link.hash = ''; // Fragment entfernen
console.log(link.href);

https://example.com/handbuch.html?v=3#installation https://example.com/handbuch.html?v=3

Sanftes Scrollen für interne Sprungmarken

document.querySelectorAll('a[href*="#"]').forEach((link) => {
  link.addEventListener('click', (event) => {
    // Nur Links auf die aktuelle Seite behandeln
    const samePage = link.origin === location.origin &&
                     link.pathname === location.pathname;
    if (!samePage || !link.hash) return;

    const target = document.getElementById(decodeURIComponent(link.hash.slice(1)));
    if (!target) return;

    event.preventDefault();
    target.scrollIntoView({ behavior: 'smooth' });
    history.pushState(null, '', link.hash);
  });
});

Aktiven Menüpunkt im Inhaltsverzeichnis markieren

const markActive = () => {
  document.querySelectorAll('nav.toc a').forEach((a) => {
    a.classList.toggle('active', a.hash === location.hash);
  });
};

window.addEventListener('hashchange', markActive);
markActive();

// Wichtig · Fallstricke

Leeres Fragment: Sowohl href="seite.html" als auch href="seite.html#" liefern "" – die beiden Fälle lassen sich über hash nicht unterscheiden.
Kodierung: Der Rückgabewert ist prozentkodiert (z. B. #%C3%BCbersicht für „übersicht“). Vor getElementById() ggf. decodeURIComponent() anwenden; bei querySelector() zusätzlich CSS.escape() verwenden, da IDs mit Ziffern oder Sonderzeichen sonst ungültige Selektoren ergeben.
Relative URLs: hash bezieht sich auf die bereits gegen die Basis-URL aufgelöste Adresse. Ein Link wie href="#abschnitt" gehört also zur aktuellen Seite – für die Prüfung „gleiche Seite“ zusätzlich origin und pathname vergleichen.
Ungültige href-Werte: Lässt sich href nicht als URL parsen, liefert hash "", und Zuweisungen haben keine Wirkung.
Sicherheit: Fragmente sind vom Nutzer kontrollierbar. Werte aus hash niemals ungeprüft in innerHTML oder eval() einsetzen (DOM-basiertes XSS).
Kompatibilität: In allen modernen Browsern unterstützt; dasselbe Verhalten bietet HTMLAreaElement.hash.

Siehe auch

Location.hash URL.hash HTMLAnchorElement.host HTMLAnchorElement.href HTMLAnchorElement.ping