0
# Search Parameters
1

2
Enhanced URLSearchParams functionality adapted for React Native applications with mobile-optimized parameter handling and React hooks integration.
3

4
## Capabilities
5

6
### useSearchParams
7

8
A convenient wrapper for accessing and modifying individual query parameters via the URLSearchParams interface. Provides React state integration for URL search parameters.
9

10
```typescript { .api }
11
/**
12
 * Hook for managing URL search parameters with React state integration
13
 * Provides current search params and setter function
14
 * @param defaultInit - Default parameters to merge when not present in URL
15
 * @returns Tuple of [searchParams, setSearchParams]
16
 */
17
function useSearchParams(
18
  defaultInit?: URLSearchParamsInit
19
): [URLSearchParams, SetURLSearchParams];
20

21
type SetURLSearchParams = (
22
  nextInit?:
23
    | URLSearchParamsInit
24
    | ((prev: URLSearchParams) => URLSearchParamsInit),
25
  navigateOpts?: NavigateOptions
26
) => void;
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import { useSearchParams } from "react-router-native";
33
import { View, Text, TextInput, TouchableOpacity } from "react-native";
34
import { useState } from "react";
35

36
// Basic search params usage
37
function SearchScreen() {
38
  const [searchParams, setSearchParams] = useSearchParams();
39
  const [query, setQuery] = useState(searchParams.get("q") || "");
40
  
41
  const handleSearch = () => {
42
    setSearchParams({ q: query });
43
  };
44
  
45
  return (
46
    <View>
47
      <Text>Current search: {searchParams.get("q") || "None"}</Text>
48
      <TextInput
49
        value={query}
50
        onChangeText={setQuery}
51
        placeholder="Search..."
52
      />
53
      <TouchableOpacity onPress={handleSearch}>
54
        <Text>Search</Text>
55
      </TouchableOpacity>
56
    </View>
57
  );
58
}
59

60
// With default parameters
61
function FilteredList() {
62
  const [searchParams, setSearchParams] = useSearchParams({
63
    sort: "name",
64
    page: "1"
65
  });
66
  
67
  const currentSort = searchParams.get("sort");
68
  const currentPage = searchParams.get("page");
69
  
70
  const updateSort = (newSort) => {
71
    setSearchParams(prev => {
72
      prev.set("sort", newSort);
73
      prev.set("page", "1"); // Reset to first page
74
      return prev;
75
    });
76
  };
77
  
78
  return (
79
    <View>
80
      <Text>Sort: {currentSort}, Page: {currentPage}</Text>
81
      <TouchableOpacity onPress={() => updateSort("date")}>
82
        <Text>Sort by Date</Text>
83
      </TouchableOpacity>
84
    </View>
85
  );
86
}
87

88
// Functional updates
89
function AdvancedFilters() {
90
  const [searchParams, setSearchParams] = useSearchParams();
91
  
92
  const addFilter = (key, value) => {
93
    setSearchParams(prev => {
94
      const newParams = new URLSearchParams(prev);
95
      newParams.append(key, value);
96
      return newParams;
97
    });
98
  };
99
  
100
  const removeFilter = (key) => {
101
    setSearchParams(prev => {
102
      const newParams = new URLSearchParams(prev);
103
      newParams.delete(key);
104
      return newParams;
105
    });
106
  };
107
  
108
  return (
109
    <View>
110
      <Text>Active filters: {searchParams.toString()}</Text>
111
      <TouchableOpacity onPress={() => addFilter("category", "electronics")}>
112
        <Text>Add Electronics Filter</Text>
113
      </TouchableOpacity>
114
      <TouchableOpacity onPress={() => removeFilter("category")}>
115
        <Text>Remove Category Filter</Text>
116
      </TouchableOpacity>
117
    </View>
118
  );
119
}
120

121
// With navigation options
122
function PaginatedList() {
123
  const [searchParams, setSearchParams] = useSearchParams({ page: "1" });
124
  
125
  const goToPage = (pageNum) => {
126
    setSearchParams(
127
      { page: pageNum.toString() },
128
      { replace: true } // Replace instead of push to avoid back button issues
129
    );
130
  };
131
  
132
  return (
133
    <View>
134
      <Text>Current page: {searchParams.get("page")}</Text>
135
      <TouchableOpacity onPress={() => goToPage(2)}>
136
        <Text>Go to Page 2</Text>
137
      </TouchableOpacity>
138
    </View>
139
  );
140
}
141
```
142

143
### createSearchParams
144

145
Creates a URLSearchParams object using the given initializer. This is identical to `new URLSearchParams(init)` except it also supports arrays as values in the object form.
146

147
```typescript { .api }
148
/**
149
 * Creates a URLSearchParams object with enhanced array support
150
 * Supports string, array, object, and URLSearchParams initializers
151
 * @param init - Initial parameters in various formats
152
 * @returns URLSearchParams instance
153
 */
154
function createSearchParams(init?: URLSearchParamsInit): URLSearchParams;
155

156
type URLSearchParamsInit =
157
  | string
158
  | ParamKeyValuePair[]
159
  | Record<string, string | string[]>
160
  | URLSearchParams;
161

162
type ParamKeyValuePair = [string, string];
163
```
164

165
**Usage Examples:**
166

167
```typescript
168
import { createSearchParams } from "react-router-native";
169

170
// From string
171
const params1 = createSearchParams("q=search&sort=name");
172
console.log(params1.get("q")); // "search"
173

174
// From object with single values
175
const params2 = createSearchParams({
176
  q: "search term",
177
  sort: "date",
178
  page: "1"
179
});
180

181
// From object with array values (multiple values for same key)
182
const params3 = createSearchParams({
183
  categories: ["electronics", "books"],
184
  tags: ["sale", "featured"]
185
});
186
console.log(params3.getAll("categories")); // ["electronics", "books"]
187

188
// From key-value pair arrays
189
const params4 = createSearchParams([
190
  ["sort", "name"],
191
  ["sort", "price"], // Multiple values for same key
192
  ["category", "electronics"]
193
]);
194

195
// From existing URLSearchParams
196
const existing = new URLSearchParams("a=1&b=2");
197
const params5 = createSearchParams(existing);
198

199
// Complex example with arrays
200
const filterParams = createSearchParams({
201
  search: "laptop",
202
  categories: ["electronics", "computers"],
203
  priceRange: ["100", "500"],
204
  inStock: "true"
205
});
206

207
// Results in: search=laptop&categories=electronics&categories=computers&priceRange=100&priceRange=500&inStock=true
208
```
209

210
## Types
211

212
```typescript { .api }
213
type URLSearchParamsInit =
214
  | string
215
  | ParamKeyValuePair[]
216
  | Record<string, string | string[]>
217
  | URLSearchParams;
218

219
type ParamKeyValuePair = [string, string];
220

221
type SetURLSearchParams = (
222
  nextInit?:
223
    | URLSearchParamsInit
224
    | ((prev: URLSearchParams) => URLSearchParamsInit),
225
  navigateOpts?: NavigateOptions
226
) => void;
227

228
// Navigation options for setSearchParams
229
interface NavigateOptions {
230
  replace?: boolean;
231
  state?: any;
232
  relative?: RelativeRoutingType;
233
}
234

235
type RelativeRoutingType = "route" | "path";
236
```
237

238
## Mobile Optimization Features
239

240
### Default Parameter Handling
241

242
- **Automatic Merging**: Default parameters are automatically merged with URL parameters
243
- **Persistent Defaults**: Default values persist even when not in the URL
244
- **Override Support**: URL parameters override defaults when present
245

246
### Array Support
247

248
- **Multiple Values**: Object initializer supports arrays for multiple values per key
249
- **Backward Compatibility**: Standard URLSearchParams behavior for string and array initializers
250
- **Convenient Syntax**: Cleaner syntax than manual array construction
251

252
### State Integration
253

254
- **React Hooks**: Full integration with React component state
255
- **Automatic Updates**: Components re-render when search parameters change
256
- **Navigation Integration**: Parameter changes trigger navigation updates
257

258
## Usage Patterns
259

260
### Search and Filtering
261

262
```typescript
263
// Typical search implementation
264
function useSearch() {
265
  const [searchParams, setSearchParams] = useSearchParams({
266
    q: "",
267
    sort: "relevance",
268
    page: "1"
269
  });
270
  
271
  const search = (query) => {
272
    setSearchParams(prev => {
273
      const newParams = new URLSearchParams(prev);
274
      newParams.set("q", query);
275
      newParams.set("page", "1"); // Reset pagination
276
      return newParams;
277
    });
278
  };
279
  
280
  return { searchParams, search };
281
}
282
```
283

284
### Pagination
285

286
```typescript
287
// Pagination with search params
288
function usePagination() {
289
  const [searchParams, setSearchParams] = useSearchParams({ page: "1" });
290
  
291
  const setPage = (page) => {
292
    setSearchParams(prev => {
293
      const newParams = new URLSearchParams(prev);
294
      newParams.set("page", page.toString());
295
      return newParams;
296
    }, { replace: true }); // Replace to avoid cluttering history
297
  };
298
  
299
  return { 
300
    currentPage: parseInt(searchParams.get("page") || "1"),
301
    setPage 
302
  };
303
}
304
```
305

306
### Multi-select Filters
307

308
```typescript
309
// Multi-select filter implementation
310
function useFilters() {
311
  const [searchParams, setSearchParams] = useSearchParams();
312
  
313
  const toggleFilter = (key, value) => {
314
    setSearchParams(prev => {
315
      const newParams = new URLSearchParams(prev);
316
      const current = newParams.getAll(key);
317
      
318
      if (current.includes(value)) {
319
        // Remove the value
320
        newParams.delete(key);
321
        current.filter(v => v !== value).forEach(v => {
322
          newParams.append(key, v);
323
        });
324
      } else {
325
        // Add the value
326
        newParams.append(key, value);
327
      }
328
      
329
      return newParams;
330
    });
331
  };
332
  
333
  return { searchParams, toggleFilter };
334
}
335
```