URLSearchParams.delete() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.delete(name, value)

Beschreibung

Die Methode delete() des Interfaces URLSearchParams löscht alle Name-Wert-Paare, deren Name dem übergebenen name entspricht. Wenn ein Parameter mehrfach vorkommt, zum Beispiel ?tag=js&tag=css, werden alle Vorkommen auf einmal entfernt.

Übergibt man zusätzlich das zweite Argument value, werden nur die Paare gelöscht, bei denen Name und Wert übereinstimmen. So lässt sich bei mehrfach vorhandenen Parametern gezielt ein einzelner Eintrag entfernen, etwa ein Filter-Tag in einer Shop-Oberfläche.

Typische Anwendungsfälle sind das Entfernen von Tracking-Parametern (utm_source, fbclid), das Zurücksetzen von Filtern oder Seitenzahlen und das Aufräumen von URLs vor history.replaceState(). Stammt das Objekt aus url.searchParams, wird die zugehörige URL sofort mitaktualisiert.

Die Methode ändert das Objekt direkt und gibt undefined zurück. Existiert der Name nicht, passiert einfach nichts; es wird kein Fehler ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Parameters, der gelöscht werden soll. Groß- und Kleinschreibung wird unterschieden. Andere Werte werden in einen String umgewandelt.
$value	string		Optional. Wenn angegeben, werden nur die Paare gelöscht, deren Wert genau diesem String entspricht. Fehlt das Argument oder ist es `undefined`, werden alle Paare mit dem Namen `name` gelöscht.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode ändert das URLSearchParams-Objekt direkt.

Beispiele

Einzelnen Parameter entfernen

const params = new URLSearchParams('q=javascript&page=3&sort=asc');

params.delete('page');

console.log(params.toString());

q=javascript&sort=asc

Tracking-Parameter aus der aktuellen URL entfernen

const url = new URL('https://example.com/artikel?id=42&utm_source=newsletter&utm_medium=mail&fbclid=abc');

const tracking = ['utm_source', 'utm_medium', 'utm_campaign', 'fbclid'];
tracking.forEach((key) => url.searchParams.delete(key));

console.log(url.href);
// Im Browser zusätzlich die Adresszeile anpassen, ohne neu zu laden:
// history.replaceState(null, '', url);

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

Mehrfach vorhandene Parameter: alle löschen oder nur einen Wert

const params = new URLSearchParams('tag=js&tag=css&tag=html&page=1');

// Nur den Filter „css“ entfernen (zweiter Parameter)
params.delete('tag', 'css');
console.log(params.getAll('tag'));

// Alle Tags entfernen
params.delete('tag');
console.log(params.toString());

[ 'js', 'html' ] page=1

Filter zurücksetzen und Seitenzahl verwerfen

const resetFilter = (href, filterName) => {
  const url = new URL(href);
  url.searchParams.delete(filterName);
  url.searchParams.delete('page'); // nach Filterwechsel wieder auf Seite 1
  return url.toString();
};

console.log(resetFilter('https://shop.example/schuhe?farbe=rot&groesse=42&page=5', 'farbe'));

https://shop.example/schuhe?groesse=42

// Wichtig · Fallstricke

Löscht alle Vorkommen: Ohne zweites Argument werden sämtliche Paare mit dem Namen entfernt, nicht nur das erste. Wenn du nur einen bestimmten Wert entfernen willst, übergib value.
Kompatibilität des value-Parameters: Der zweite Parameter wird erst seit Chrome/Edge 117, Firefox 115, Safari 17 und Node.js 20.2 unterstützt. Ältere Umgebungen ignorieren ihn stillschweigend und löschen dann alle Paare mit dem Namen. Das kann zu unerwartetem Datenverlust führen. Eine portable Alternative: const rest = params.getAll('tag').filter((v) => v !== 'css'); params.delete('tag'); rest.forEach((v) => params.append('tag', v));
Nicht während der Iteration löschen: Wenn du innerhalb von for...of bzw. forEach() über dasselbe Objekt löschst, werden Einträge übersprungen. Sammle die Schlüssel vorher, z. B. mit [...params.keys()].
Groß- und Kleinschreibung wird unterschieden: delete('Page') entfernt page nicht.
Bleiben nach dem Löschen keine Parameter übrig, liefert url.search einen leeren String und url.href enthält kein ? mehr.
Ein URLSearchParams-Objekt, das mit new URLSearchParams(location.search) erzeugt wurde, ist nicht mit der Adresszeile verbunden. Die Änderungen musst du selbst übernehmen, etwa mit history.replaceState().

Siehe auch

URLSearchParams URLSearchParams.append() URLSearchParams.set() URLSearchParams.has() URLSearchParams.getAll() URL.searchParams History.replaceState()