URL et URLSearchParams en JavaScript : guide pratique

Arrêtez de parser les URL à coups de split

Avant l'arrivée de l'API URL, on découpait les URL avec split('?'), des regex maison et pas mal d'espoir. Ça tenait la route… jusqu'à ce qu'une valeur contienne un &, un =, un espace ou un caractère non-ASCII — et là, tout partait en vrille. Le navigateur comme Node embarquent un vrai parser. Autant s'en servir.

Un seul appel, et toutes les parties de l'URL sont déjà découpées et décodées correctement. Le constructeur lève une TypeError si l'entrée est invalide, et c'est généralement ce que vous voulez : une URL malformée doit échouer bruyamment plutôt que propager des données corrompues en silence.

Lire les paramètres d'une query string

Chaque objet URL expose une propriété .searchParams — un objet URLSearchParams qui sait lire et écrire la query string :

Quelques points à garder en tête :

• Les valeurs sont renvoyées déjà décodées. ?name=Ada%20Lovelace vous donne "Ada Lovelace".
• Tout est une chaîne de caractères. "2" n'est pas 2. Utilisez Number() si vous avez besoin d'un nombre.
• Les clés en double sont autorisées. get renvoie la première occurrence, getAll renvoie toutes les correspondances.
• Une clé absente renvoie null, pas undefined — du coup ?? "default" s'utilise très bien avec.

Construire une query string en JavaScript

On peut construire une query string de toutes pièces avec URLSearchParams — pas besoin d'échapper à la main ni de recoller les morceaux avec des & :

Tu peux aussi le construire à partir d'un objet — n'importe quel itérable de paires [key, value] fonctionne, et un objet simple aussi :

set ou append : set remplace la valeur existante associée à la clé, tandis que append en ajoute une nouvelle. On utilise append quand une clé peut légitimement apparaître plusieurs fois (tags, filtres), et set pour les paramètres à valeur unique.

Modifier une URL en JavaScript

Comme URL est un objet vivant, toute modification de searchParams met automatiquement à jour .search et .href :

C'est la façon idiomatique d'ajouter un paramètre à une URL existante. Pas besoin de vérifier si l'URL contient déjà un ?, ni de se demander s'il faut préfixer avec & ou ?.

Tu peux modifier les autres parties de l'URL de la même manière :

Itérer sur les paramètres

URLSearchParams est itérable. Une boucle for...of te renvoie des paires [clé, valeur], et tu disposes aussi des méthodes classiques keys(), values() et entries() :

Attention : les clés répétées apparaissent plusieurs fois — tu verras d'abord tag = web, puis tag = beginner comme deux entrées distinctes. C'est fidèle à ce que contient réellement la query string.

Si tu veux un objet simple pour un console.log rapide, Object.fromEntries fait le job — mais il écrase les doublons et ne garde que la dernière valeur :

Pratique pour débugger. Par contre, ça casse dès qu'une clé peut apparaître plusieurs fois.

Les URL relatives ont besoin d'une base

Tout seul, new URL("/search?q=js") lève une erreur — un chemin relatif n'est pas une URL valide en soi. Il faut passer une base en second argument :

Les règles de résolution sont exactement celles que les navigateurs appliquent à <a href> : un / en tête part de la racine du domaine, sans slash on reste relatif au chemin courant, et .. remonte d'un niveau. Très pratique quand on assemble des URLs d'API à partir d'une base configurée.

Côté navigateur, window.location.href fait une base toute prête pour parser l'URL de la page en cours :

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

Gérer les URLs invalides

Le constructeur URL lève une exception quand l'entrée est mal formée. C'est plutôt pratique, mais ça veut dire qu'il faut systématiquement un try/catch dès que tu parses une URL saisie par l'utilisateur ou reçue d'un système externe :

Les environnements récents exposent aussi URL.canParse(input) — une méthode qui retourne un booléen et qui t'évite la gymnastique du try/catch quand tu veux juste valider une URL :

Un petit exemple concret

On met tout ça bout à bout : on lit les filtres actuels depuis une URL, on les ajuste, puis on génère une nouvelle URL vers laquelle naviguer :

Passer null supprime le paramètre. Toute autre valeur le définit ou l'écrase. C'est un pattern que tu finiras par écrire d'une façon ou d'une autre dès que tu construiras des UI de filtres, de la pagination ou des liens profonds.

Ce qu'il faut retenir

• new URL(string) découpe une URL en morceaux nommés. Il lève une exception sur une entrée bidon.
• url.searchParams est un objet URLSearchParams — utilise get, getAll, set, append, delete, has.
• L'encodage est géré automatiquement. Pas besoin de dégainer encodeURIComponent, sauf si tu construis des chaînes à la main.
• Passe une URL de base en deuxième argument pour résoudre les chemins relatifs.
• URL.canParse (ou un try/catch) est ton outil de validation pour les entrées non fiables.

À chaque fois que tu seras tenté de découper une URL avec .split('?') ou d'extraire un paramètre de query string avec une regex, utilise plutôt ces API. C'est plus court, c'est correct, et c'est déjà dans le runtime.