How to Use URLSearchParams in Node.js: Syntax and Examples

In Node.js, you can use the URLSearchParams class to create, read, and manipulate query strings easily. It provides methods like append, get, and toString to work with URL parameters. This class is available globally in Node.js versions 10 and above.

Syntax

The URLSearchParams class is used to work with query strings. You create an instance by passing a query string or an object. Common methods include:

• append(name, value): Adds a new parameter.
• get(name): Retrieves the first value of a parameter.
• set(name, value): Sets or updates a parameter.
• delete(name): Removes a parameter.
• toString(): Returns the full query string.

javascript

const params = new URLSearchParams('foo=1&bar=2');
params.append('baz', '3');
console.log(params.toString());

Output

foo=1&bar=2&baz=3

Example

This example shows how to create a URLSearchParams object, add parameters, get values, and convert it back to a query string.

javascript

const params = new URLSearchParams();

// Add parameters
params.append('name', 'Alice');
params.append('age', '30');

// Get a parameter value
const name = params.get('name');
console.log('Name:', name);

// Update a parameter
params.set('age', '31');

// Delete a parameter
params.delete('nonexistent'); // no error if not found

// Output the full query string
console.log(params.toString());

Output

Name: Alice
name=Alice&age=31

Common Pitfalls

Some common mistakes when using URLSearchParams in Node.js include:

• Passing an incomplete or malformed query string to the constructor.
• Expecting get() to return all values when multiple exist; it only returns the first.
• Using append() when you want to replace a value; use set() instead.
• Not converting the object back to a string with toString() before using it in URLs.

javascript

/* Wrong: Using append to replace value */
const params = new URLSearchParams('key=old');
params.append('key', 'new');
console.log(params.toString()); // Outputs: key=old&key=new

/* Right: Use set to replace value */
const params2 = new URLSearchParams('key=old');
params2.set('key', 'new');
console.log(params2.toString()); // Outputs: key=new

Output

key=old&key=new
key=new

Quick Reference

Method	Description
append(name, value)	Add a new parameter without removing existing ones
set(name, value)	Set or update a parameter, replacing existing values
get(name)	Get the first value of a parameter
getAll(name)	Get all values of a parameter as an array
delete(name)	Remove a parameter
has(name)	Check if a parameter exists
toString()	Convert parameters back to a query string

Key Takeaways

Use URLSearchParams to easily create and manipulate query strings in Node.js.

Use append() to add parameters and set() to replace them.

Always convert URLSearchParams back to a string with toString() before using it in URLs.

The get() method returns only the first value for a parameter; use getAll() for multiple values.

This API is built-in and available globally in Node.js 10+ without extra packages.