Pare de Fazer Parse de URL na Gambiarra
Antes da API URL existir, o pessoal cortava URL no split('?'), regex e muita fé. Funcionava na maioria dos casos — até o momento em que algum valor tinha um &, um =, um espaço ou um caractere fora do ASCII. Aí o esquema desandava. Tanto o navegador quanto o Node já trazem um parser de verdade embutido. Use ele.
Uma única chamada e pronto: cada pedaço da URL já vem separado e decodificado corretamente. O construtor lança um TypeError quando recebe uma entrada inválida, o que normalmente é o comportamento desejado — é melhor uma URL bagunçada falhar de cara do que seguir produzindo lixo silenciosamente lá na frente.
Como ler parâmetros da query string em JavaScript
Todo objeto URL tem uma propriedade .searchParams — um URLSearchParams que sabe ler e escrever na query string:
Alguns detalhes que vale a pena observar:
- Os valores já voltam decodificados.
?name=Ada%20Lovelacete devolve"Ada Lovelace". - Tudo vem como string.
"2"não é2. Se precisar de número, converta comNumber(). - Chaves repetidas são permitidas. O
getretorna a primeira ocorrência; ogetAllretorna todas. - Chaves inexistentes retornam
null, nãoundefined— então o operador?? "default"funciona direitinho.
Como montar uma query string em JavaScript
Dá pra montar uma query string do zero com URLSearchParams — sem precisar escapar nada na mão, sem ficar juntando tudo com &:
Ou então monte ele a partir de um objeto — qualquer iterável de pares [chave, valor] funciona, e um objeto literal também serve:
set vs append: o set substitui qualquer valor já existente para aquela chave. Já o append adiciona mais um. Use append quando faz sentido a chave se repetir (tags, filtros) e set para parâmetros de valor único.
Alterando uma URL
Como o URL é um objeto vivo, qualquer mudança em searchParams reflete automaticamente em .search e .href:
Essa é a forma idiomática de adicionar um parâmetro na query string de uma URL já existente. Sem precisar verificar se a URL já tem um ?, sem ficar se preocupando se é caso de colocar & ou ? na frente.
Dá pra alterar outras partes da URL do mesmo jeito:
Iterando sobre os parâmetros
URLSearchParams é iterável. Usando for...of, você recebe pares [chave, valor], e ainda conta com os métodos keys(), values() e entries() para facilitar:
Vale notar que chaves repetidas aparecem mais de uma vez — você vai ver tag = web e depois tag = beginner como entradas separadas. Isso reflete fielmente o que está na query string.
Se você só quer um objeto simples para dar um console.log rápido, dá pra usar Object.fromEntries — só lembrando que ele achata as repetições e mantém apenas o último valor:
Serve só pra debug. Dá problema na hora que alguma chave aparece repetida.
URLs relativas precisam de uma base
new URL("/search?q=js") sozinho lança erro — um caminho relativo não é uma URL válida por si só. Passe uma base como segundo argumento:
As regras de resolução são as mesmas que o navegador aplica em <a href>: uma barra / no início é absoluta a partir do host, sem barra é relativo ao caminho atual, e .. sobe um nível. Isso salva a sua vida quando você está montando URLs de API a partir de uma base configurada.
No navegador, window.location.href já serve como base pronta para fazer o parse da URL da página atual:
const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";
Como lidar com URLs inválidas
O construtor URL lança uma exceção quando recebe uma entrada malformada. Isso até ajuda — mas significa que você precisa de try/catch sempre que for parsear algo digitado pelo usuário ou vindo de um sistema externo:
Ambientes modernos também expõem URL.canParse(input) — uma verificação booleana que dispensa aquele try/catch quando você só quer validar:
Um exemplo prático rodando
Juntando tudo: ler os filtros atuais de uma URL, ajustar os valores e gerar uma nova URL para navegar:
Passar null remove o parâmetro. Qualquer outro valor define ou sobrescreve o atual. Esse é o padrão que você vai acabar escrevendo de um jeito ou de outro sempre que montar UIs de filtro, paginação ou deep links.
O que levar desta leitura
new URL(string)faz o parse da URL e separa em partes nomeadas. Se vier lixo, ele lança erro.url.searchParamsé umURLSearchParams— useget,getAll,set,append,deleteehas.- O encoding é feito automaticamente. Só recorra a
encodeURIComponentse estiver montando strings na mão. - Passe uma URL base como segundo argumento para resolver caminhos relativos.
URL.canParse(outry/catch) é sua ferramenta de validação para entradas não confiáveis.
Toda vez que bater a vontade de quebrar uma URL com .split('?') ou pescar um parâmetro da query com regex, use essas APIs no lugar. Elas são mais curtas, corretas e já vêm prontas no runtime.
Perguntas frequentes
Como fazer o parse de uma URL em JavaScript?
Basta passar a string para o construtor URL: const u = new URL('https://example.com/path?x=1'). O objeto resultante expõe protocol, host, pathname, search, hash e o auxiliar searchParams. Ele lança erro quando a URL é inválida, então vale envolver em try/catch se a entrada não for confiável.
Como pegar um parâmetro da query string em JavaScript?
Use url.searchParams.get('nome'). Ele devolve o valor já decodificado, ou null quando o parâmetro não existe. Para parâmetros que podem se repetir (?tag=a&tag=b), chame searchParams.getAll('tag') e receba todos os valores em um array.
Qual a diferença entre URL e URLSearchParams?
O URL representa a URL inteira — protocolo, host, caminho, query e hash. Já o URLSearchParams cuida só da query string, e você pode usá-lo sozinho para montar ou ler algo como a=1&b=2. Toda instância de URL tem uma propriedade .searchParams, que é justamente um URLSearchParams ligado àquela URL.
Preciso codificar os parâmetros da query string na mão?
Não. O URLSearchParams codifica chaves e valores automaticamente ao usar set, append ou quando você lê a string de volta. Isso resolve espaços, &, = e caracteres Unicode do jeito certo. Só recorra a encodeURIComponent se você estiver montando a string manualmente — coisa que, na prática, quase nunca é necessário.
