Learning Tips | Published Nov 17, 2026 | 8 min read

JavaScript URLSearchParams: Parse, Update, and Validate URLs

Learn URLSearchParams get, getAll, set, append, encoding, duplicate keys, and safe validation for JavaScript query strings.

Flow diagram shows a query URL parsed by URLSearchParams, read with get and getAll, updated with set or append, and serialized back to an encoded URL

URLSearchParams provides a safer, clearer way to read and build query strings in JavaScript. Learn how to parse values, preserve repeated keys, update URLs, handle encoding correctly, and validate untrusted parameters before using them.

Query strings carry filters, search terms, pagination, and other state in a URL. Splitting them by & and = seems simple, but percent encoding, repeated keys, and spaces quickly make manual parsing error-prone. The URL and URLSearchParams APIs handle the format for you.

Parse a URL using URL.searchParams

const url = new URL(window.location.href);
const params = url.searchParams;

const query = params.get("q") ?? "";
const pageText = params.get("page");
const page = Number(pageText);

if (!Number.isInteger(page) || page < 1) {
  // Use a safe default or show a validation message.
}

get() returns the first value for a key, or null when it is missing. Query parameters are user-controlled input. Convert and validate them before using them as page numbers, sort fields, database filters, or navigation destinations.

Repeated parameters need explicit handling

A URL can contain the same key more than once, such as ?tag=css&tag=html. get("tag") returns the first value. Use getAll("tag") to read every value, or iterate over params to inspect all key-value pairs.

const tags = params.getAll("tag");
for (const tag of tags) {
  addTagFilter(tag);
}

Choose a rule for duplicates based on your application contract: accept a list, use the first, use the last, or reject ambiguous input. Do not assume a parameter appears only once if clients can construct the URL.

Build and update parameters

Create a URL object and modify its searchParams. Use set() for a single value, which replaces existing values for that key, and append() when another value should be added.

const url = new URL("/courses", window.location.origin);
url.searchParams.set("q", "web development");
url.searchParams.append("level", "beginner");
url.searchParams.append("level", "intermediate");

history.replaceState(null, "", url);

Use delete() to remove a filter and has() to check whether a key is present. When modifying the current URL, decide whether to use pushState (adds a history entry) or replaceState (updates the current entry). For substantial navigation state, ensure the page also handles back and forward navigation.

Let the API encode values

Pass decoded values to set() and append(); the API handles serialization. Avoid manually concatenating a dynamic string into the constructor, since a literal plus sign in form-style query syntax is interpreted as a space. Passing a value to append() preserves the value and encodes it for the query string.

const params = new URLSearchParams();
params.append("token", "A+B/C");
const queryString = params.toString();

toString() returns the query string without a leading question mark. Spaces serialize as + under the form URL-encoding rules. Re-serializing a URL may normalize encoding and character choices; do not expect the exact original query-string bytes to remain unchanged.

Safely use query values

Encoding protects the URL structure; it does not make a value trusted or safe for every context. Validate allowed values, bound list sizes, and use allowlists for choices such as sort fields. Never treat a query value as authorization. Do not insert it into HTML with innerHTML; use text nodes or context-appropriate escaping. On the server, validate again because clients can bypass browser-side checks.

Test practical edge cases

  • Missing, empty, malformed, and out-of-range values.
  • Repeated keys and the difference between get() and getAll().
  • Spaces, plus signs, ampersands, Unicode, and percent-encoded data.
  • Whether changing filters should create a browser history entry.
  • Whether the server and client agree on duplicate-value behavior.

Use URLSearchParams for structured query manipulation, define how duplicate keys work, and validate every value at the point it is used. That keeps links readable while avoiding fragile manual parsing and accidental trust in URL input.

Want a structured Java learning path?

Explore Jaipur Engineers course options to connect Java fundamentals, debugging, backend development and project practice in a guided learning plan.

Explore the Java program   Ask for course guidance