Location.search — Eigenschaft · JavaScript-Referenz

Signatur

Location.search

Beschreibung

Die Eigenschaft location.search liefert den Abfrageteil der aktuellen Dokument-URL – also alles ab dem ? bis vor ein eventuelles #-Fragment. Bei https://example.com/suche?q=js&seite=2#treffer ergibt sie "?q=js&seite=2". Gibt es keine Parameter, ist der Wert ein leerer String "".

Typischerweise nutzt man location.search, um Filter, Suchbegriffe, Tracking-Parameter oder Seitenzahlen auszulesen. Am bequemsten geht das zusammen mit URLSearchParams, das den String zerlegt und die Werte automatisch dekodiert.

Die Eigenschaft ist auch beschreibbar: Wird ein neuer Wert zugewiesen, navigiert der Browser zur geänderten URL und lädt die Seite neu, wobei ein neuer Eintrag im Verlauf entsteht. Ein fehlendes ? wird dabei automatisch ergänzt. Wer die URL ohne Neuladen ändern möchte, verwendet stattdessen history.pushState() oder history.replaceState().

Parameter

Name	Typ	Default	Beschreibung
$wert	string		Nur beim Setzen: neue Abfragezeichenfolge, mit oder ohne führendes `?`. Die Zuweisung löst eine Navigation aus.

Rückgabewert

Typ

string

Beschreibung

Die Abfragezeichenfolge inklusive führendem ? in prozentkodierter Form, oder "", wenn die URL keine Parameter enthält.

Beispiele

Query-String auslesen

// URL: https://example.com/produkte?kategorie=buecher&sort=preis
console.log(location.search);

?kategorie=buecher&sort=preis

Parameter mit URLSearchParams auswerten

// URL: https://example.com/suche?q=caf%C3%A9&seite=3
const params = new URLSearchParams(location.search);
const begriff = params.get('q') ?? '';
const seite = Number(params.get('seite') ?? 1);
console.log(begriff, seite, params.has('debug'));

café 3 false

Filter setzen und neu laden

const params = new URLSearchParams(location.search);
params.set('sort', 'datum');
params.delete('seite');
// Löst eine Navigation mit Neuladen aus
location.search = params.toString();

URL ohne Neuladen aktualisieren

const aktualisiereFilter = (key, value) => {
  const url = new URL(location.href);
  url.searchParams.set(key, value);
  history.replaceState(null, '', url);
  console.log(location.search);
};

aktualisiereFilter('farbe', 'rot');

?farbe=rot

// Wichtig · Fallstricke

Der Wert ist prozentkodiert. Beim manuellen Zerlegen muss man mit decodeURIComponent() dekodieren und auf + als Leerzeichen achten. URLSearchParams erledigt beides automatisch.
Das Setzen von location.search lädt die Seite immer neu, sogar bei identischem Wert. Für Single-Page-Apps sind history.pushState() bzw. replaceState() besser geeignet.
Das Hash-Fragment gehört nicht dazu: Bei ?a=1#x liefert search nur ?a=1. Ein ? hinter dem # gilt als Teil von location.hash.
Sicherheit: Werte aus dem Query-String kommen vom Nutzer und sind nicht vertrauenswürdig. Nie ungeprüft per innerHTML oder document.write einfügen (DOM-basiertes XSS), sondern textContent verwenden. Auch Weiterleitungsziele aus Parametern prüfen (Open Redirect).
Wird die Eigenschaft auf einer about:blank- oder data:-URL gelesen, ist sie meist leer. Auf Location-Objekten fremder Ursprünge (z. B. in iframes) ist Lesen durch die Same-Origin-Policy gesperrt.

Siehe auch

Location URLSearchParams Location.hash Location.href URL.searchParams History.replaceState() ScrollTimeline.source