HTMLAnchorElement.search — Eigenschaft · JavaScript-Referenz

Signatur

HTMLAnchorElement.search

Beschreibung

Die Eigenschaft search von HTMLAnchorElement liefert den Suchteil (Query String) der URL, die im href-Attribut eines <a>-Elements steht. Der Wert beginnt mit einem ?, gefolgt von den Parametern, z. B. "?q=js&page=2". Hat die URL keinen Query String, ist der Wert ein leerer String.

Die Eigenschaft ist les- und schreibbar. Beim Setzen wird das href-Attribut automatisch aktualisiert; ein fehlendes führendes ? wird ergänzt, und Sonderzeichen werden prozentkodiert. Andere URL-Bestandteile wie Pfad oder Fragment (hash) bleiben unverändert.

Typische Einsatzfälle sind das Auslesen von Parametern aus Links (z. B. zur Analyse oder zum Tracking), das nachträgliche Anhängen von Parametern an bestehende Links oder das Entfernen von Tracking-Parametern. Für die komfortable Verarbeitung einzelner Parameter kombiniert man search am besten mit URLSearchParams.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: neuer Query String, mit oder ohne führendes `?`. Ein leerer String entfernt den Query String.

Rückgabewert

Typ

string

Beschreibung

Der Query String der Link-URL inklusive führendem ?, oder "", wenn keiner vorhanden ist (oder das href ungültig ist bzw. fehlt).

Beispiele

Query String eines Links auslesen

const link = document.createElement('a');
link.href = 'https://example.com/suche?q=javascript&seite=2#ergebnisse';

console.log(link.search);
console.log(link.hash);

?q=javascript&seite=2 #ergebnisse

Parameter mit URLSearchParams auswerten

const link = document.createElement('a');
link.href = '/produkte?kategorie=buecher&sortierung=preis';

const params = new URLSearchParams(link.search);
console.log(params.get('kategorie'));
console.log(params.has('sortierung'));

buecher true

Parameter an alle externen Links anhängen

document.querySelectorAll('a[href^="http"]').forEach((a) => {
  const params = new URLSearchParams(a.search);
  params.set('ref', 'programmierung.net');
  a.search = params.toString(); // '?' wird automatisch ergänzt
  console.log(a.href);
});

https://example.com/seite?ref=programmierung.net

Tracking-Parameter entfernen

const link = document.createElement('a');
link.href = 'https://example.com/artikel?id=42&utm_source=news&utm_medium=mail';

const params = new URLSearchParams(link.search);
for (const key of [...params.keys()]) {
  if (key.startsWith('utm_')) params.delete(key);
}
link.search = params.toString();
console.log(link.href);

https://example.com/artikel?id=42

// Wichtig · Fallstricke

Der Rückgabewert enthält das führende ?. new URLSearchParams(link.search) kommt damit zurecht; bei manueller Zerlegung per split('&') muss das ? aber zuerst entfernt werden.
Werte sind prozentkodiert (z. B. %20 für Leerzeichen). Zum Dekodieren URLSearchParams oder decodeURIComponent() verwenden.
Ein ? ohne Parameter (href="/seite?") liefert "" – man kann so nicht zwischen „kein Query String“ und „leerer Query String“ unterscheiden.
Relative href-Werte werden gegen die Basis-URL des Dokuments aufgelöst. Bei ungültigen URLs liefert search einen leeren String; Setzen hat dann keine Wirkung.
Werte aus Query Strings stammen oft aus Benutzereingaben – vor Ausgabe per innerHTML unbedingt escapen (XSS-Gefahr), besser textContent nutzen.
Von allen gängigen Browsern seit langem unterstützt; das Verhalten entspricht URL.prototype.search und Location.search.

Siehe auch

URL.search Location.search HTMLAnchorElement.hash HTMLAnchorElement.href HTMLAnchorElement.port