0
# URLSearchParams Class
1

2
The URLSearchParams class provides utilities for working with URL query strings, offering a standardized interface for parsing, modifying, and serializing query parameters.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a URLSearchParams instance from various input types.
9

10
```javascript { .api }
11
/**
12
 * Creates a URLSearchParams instance
13
 * @param {string|URLSearchParams|Array<Array<string>>|Object} [init=""] - Initial data
14
 */
15
constructor(init)
16
```
17

18
**Supported input types:**
19

20
- **String**: Query string with or without leading "?"
21
- **URLSearchParams**: Another URLSearchParams instance (creates a copy)
22
- **Array**: Array of key-value pairs `[["key1", "value1"], ["key2", "value2"]]`
23
- **Object**: Plain object with string keys and values
24

25
**Usage Examples:**
26

27
```javascript
28
const { URLSearchParams } = require("whatwg-url");
29

30
// From string
31
const params1 = new URLSearchParams("?name=John&age=30");
32
const params2 = new URLSearchParams("name=John&age=30"); // works without ?
33

34
// From array of pairs
35
const params3 = new URLSearchParams([
36
  ["name", "John"],
37
  ["age", "30"],
38
  ["hobby", "reading"],
39
  ["hobby", "coding"] // multiple values for same key
40
]);
41

42
// From object
43
const params4 = new URLSearchParams({
44
  name: "John",
45
  age: "30",
46
  active: "true"
47
});
48

49
// Copy constructor
50
const params5 = new URLSearchParams(params1);
51
```
52

53
### Properties
54

55
#### size
56

57
The number of key-value pairs. Read-only.
58

59
```javascript { .api }
60
/**
61
 * Number of key-value pairs (readonly)
62
 * @type {number}
63
 */
64
size
65
```
66

67
**Usage Example:**
68

69
```javascript
70
const params = new URLSearchParams("name=John&age=30&hobby=reading");
71
console.log(params.size); // 3
72
```
73

74
### Methods
75

76
#### append
77

78
Adds a new key-value pair without replacing existing ones.
79

80
```javascript { .api }
81
/**
82
 * Add a key-value pair without replacing existing values
83
 * @param {string} name - Parameter name
84
 * @param {string} value - Parameter value
85
 */
86
append(name, value)
87
```
88

89
#### delete
90

91
Removes all key-value pairs with the specified name, or optionally only those with a specific value.
92

93
```javascript { .api }
94
/**
95
 * Remove key-value pairs by name, optionally by specific value
96
 * @param {string} name - Parameter name to remove
97
 * @param {string} [value] - Specific value to remove (if provided)
98
 */
99
delete(name, value)
100
```
101

102
#### get
103

104
Returns the first value for the specified name, or null if not found.
105

106
```javascript { .api }
107
/**
108
 * Get the first value for a parameter name
109
 * @param {string} name - Parameter name
110
 * @returns {string|null} First value or null if not found
111
 */
112
get(name)
113
```
114

115
#### getAll
116

117
Returns an array of all values for the specified name.
118

119
```javascript { .api }
120
/**
121
 * Get all values for a parameter name
122
 * @param {string} name - Parameter name
123
 * @returns {string[]} Array of all values (empty array if none found)
124
 */
125
getAll(name)
126
```
127

128
#### has
129

130
Checks if a parameter exists, optionally with a specific value.
131

132
```javascript { .api }
133
/**
134
 * Check if parameter exists, optionally with specific value
135
 * @param {string} name - Parameter name
136
 * @param {string} [value] - Specific value to check for
137
 * @returns {boolean} True if parameter exists (with value if specified)
138
 */
139
has(name, value)
140
```
141

142
#### set
143

144
Sets the value for a parameter, replacing all existing values for that name.
145

146
```javascript { .api }
147
/**
148
 * Set value for parameter, replacing all existing values
149
 * @param {string} name - Parameter name
150
 * @param {string} value - Parameter value
151
 */
152
set(name, value)
153
```
154

155
#### sort
156

157
Sorts all key-value pairs by key name using Unicode code points.
158

159
```javascript { .api }
160
/**
161
 * Sort all key-value pairs by key name
162
 */
163
sort()
164
```
165

166
#### toString
167

168
Returns the serialized query string without leading "?".
169

170
```javascript { .api }
171
/**
172
 * Serialize to query string without leading "?"
173
 * @returns {string} Serialized query string
174
 */
175
toString()
176
```
177

178
**Usage Examples:**
179

180
```javascript
181
const params = new URLSearchParams();
182

183
// Add parameters
184
params.append("name", "John");
185
params.append("hobby", "reading");
186
params.append("hobby", "coding"); // multiple values
187

188
console.log(params.toString()); // "name=John&hobby=reading&hobby=coding"
189

190
// Check and get values
191
console.log(params.has("name")); // true
192
console.log(params.has("hobby", "reading")); // true
193
console.log(params.get("name")); // "John"
194
console.log(params.getAll("hobby")); // ["reading", "coding"]
195

196
// Modify parameters
197
params.set("name", "Jane"); // replaces existing
198
params.delete("hobby", "reading"); // removes only this value
199
console.log(params.toString()); // "name=Jane&hobby=coding"
200

201
// Sort parameters
202
params.append("age", "30");
203
params.sort();
204
console.log(params.toString()); // "age=30&hobby=coding&name=Jane"
205
```
206

207
### Iteration
208

209
URLSearchParams implements the iterable protocol, allowing iteration over key-value pairs.
210

211
```javascript { .api }
212
/**
213
 * Iterator for key-value pairs
214
 * @returns {Iterator<[string, string]>} Iterator yielding [key, value] pairs
215
 */
216
[Symbol.iterator]()
217
```
218

219
**Usage Examples:**
220

221
```javascript
222
const params = new URLSearchParams("name=John&age=30&hobby=reading");
223

224
// For-of loop
225
for (const [key, value] of params) {
226
  console.log(`${key}: ${value}`);
227
}
228
// Output:
229
// name: John
230
// age: 30
231
// hobby: reading
232

233
// Destructuring
234
const entries = [...params];
235
console.log(entries); // [["name", "John"], ["age", "30"], ["hobby", "reading"]]
236

237
// Array methods
238
const keys = [...params].map(([key]) => key);
239
console.log(keys); // ["name", "age", "hobby"]
240
```
241

242
### Integration with URL
243

244
URLSearchParams automatically syncs with associated URL instances when modified.
245

246
**Usage Example:**
247

248
```javascript
249
const { URL } = require("whatwg-url");
250

251
const url = new URL("https://example.com?name=John&age=30");
252

253
// Modify through searchParams
254
url.searchParams.set("age", "31");
255
url.searchParams.append("city", "New York");
256

257
console.log(url.href); // "https://example.com/?name=John&age=31&city=New+York"
258
console.log(url.search); // "?name=John&age=31&city=New+York"
259
```