# JavaScript URL, FormData & Search Params: A Practical Guide

Source: https://devdocs10.com/articles/javascript/js-url-forms  
By Murat Bo · Published 2026-07-17 · DevDocs10 (https://devdocs10.com)

URL, FormData, and search params are three closely related browser APIs that help you work with links, query strings, and form submissions in vanilla JavaScript. Together, they let you read values from the current address, build request data, and turn form fields into a format that is easy to send or share.

> **Quick answer:** Use `URL` to parse and modify full addresses, `URLSearchParams` to read and change query strings, and `FormData` to collect form fields or prepare request bodies. They solve different parts of the same workflow.

> **Difficulty:** Beginner to Intermediate
>
> **You'll understand this better if you know:** basic JavaScript objects, DOM forms, and how browser URLs use query strings after the `?` symbol.

## 1. What Are URL, FormData & Search Params?

These APIs are built into modern browsers and give you structured ways to work with web addresses and form values.

- `URL` represents a complete URL and exposes its parts, such as the path, origin, and query string.
- `URLSearchParams` represents the key-value pairs in the query string portion of a URL.
- `FormData` represents form fields as name/value pairs, similar to what a browser sends when submitting a form.

These APIs are related because they all handle structured data, but they are not interchangeable. A `URL` is for addresses, `URLSearchParams` is for query strings, and `FormData` is for form payloads.

## 2. Why They Matter

Web apps constantly need to read filters from the address bar, build links with parameters, and send form input to servers. These APIs avoid manual string building and make those tasks safer and clearer.

They also reduce bugs caused by missing encoding, broken separators, or incorrect parsing. Instead of concatenating strings by hand, you can let the browser handle details like spaces, special characters, and repeated keys.

Common real-world uses include:

- Reading search, sort, or pagination values from the current page URL.
- Updating the address bar when a user changes filters without reloading the page.
- Collecting form values before sending them with `fetch()`.
- Building links that preserve state, such as selected tags or language preferences.

## 3. Basic Syntax

At the simplest level, you create a `URL` from a string, read or change its search params, and use `FormData` with a form element or as a request body.

### Creating and reading a URL

The `URL` constructor parses a full address into parts you can inspect and edit.

```javascript
const url = new URL("https://example.com/products?category=books");

console.log(url.origin); // https://example.com
console.log(url.pathname); // /products
console.log(url.search); // ?category=books
```

Output (tested with Node 24.21.0):

```text
https://example.com
/products
?category=books
```

The constructor does the parsing for you, and each property gives you a specific piece of the address.

### Reading search parameters

`URLSearchParams` turns the query string into readable entries.

```javascript
const params = new URLSearchParams("category=books&sort=price");

console.log(params.get("category")); // books
console.log(params.get("sort")); // price
```

Output (tested with Node 24.21.0):

```text
books
price
```

The `get()` method returns the first value for a key, which is important when duplicate keys exist.

### Reading form data

`FormData` reads field values from a form element.

```javascript
const form = document.querySelector("form");
const data = new FormData(form);

console.log(data.get("email"));
```

That gives you form values without manually reading every input one by one.

## 4. Step-by-Step Examples

### Example 1: Read the current page query string

This example reads parameters from the browser address bar and uses them to show the selected filter values.

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

const page = params.get("page") || "1";
const sort = params.get("sort") || "popular";

console.log(`Page: ${page}, Sort: ${sort}`);
```

This is a common pattern for filters, search results, and dashboard state that should survive refreshes.

### Example 2: Update a query string safely

Instead of building a query string manually, update the existing `URL` object and let the API handle encoding.

```javascript
const url = new URL(window.location.href);

url.searchParams.set("category", "science fiction");
url.searchParams.set("page", "2");

console.log(url.toString());
```

Notice that the space in "science fiction" is encoded correctly when the URL is serialized.

### Example 3: Convert form input into query parameters

Sometimes you want a form to drive a search URL instead of immediately sending a POST request.

```javascript
const form = document.querySelector("#search-form");
const formData = new FormData(form);
const params = new URLSearchParams(formData);

console.log(params.toString());
```

This works well when your form fields should become `?key=value` pairs for a GET-style search URL.

### Example 4: Send FormData with fetch

`FormData` is also useful when sending multipart form content to a server.

```javascript
const form = document.querySelector("#profile-form");
const formData = new FormData(form);

fetch("/api/profile", {
  method: "POST",
  body: formData
});
```

This is especially useful for file uploads and forms that do not need manual JSON conversion.

## 5. Practical Use Cases

- Search pages that keep the current query in the address bar so users can bookmark or share it.
- Filters such as category, price range, or sort order stored in query parameters.
- Form submissions that need to send files, checkboxes, or multiple values without manual serialization.
- Progressive enhancement, where a form works normally but JavaScript also reads and updates its data.
- Client-side routing and state restoration in browser applications that use plain links.

## 6. Common Mistakes

### Mistake 1: Building query strings by hand

Beginners often join strings manually and forget to encode spaces or special characters. That works for simple values, but it breaks quickly with real user input.

**Problem:** The value "red shoes & socks" contains spaces and an ampersand, so the resulting URL becomes ambiguous and may be parsed incorrectly.

```javascript
const category = "red shoes & socks";
const url = "/products?category=" + category;
```

**Fix:** Use `URLSearchParams` or `URL.searchParams` so encoding is handled for you.

```javascript
const params = new URLSearchParams();
params.set("category", "red shoes & socks");

const url = "/products?" + params.toString();
```

The corrected version works because the API produces a valid encoded query string.

### Mistake 2: Using `FormData` on the wrong element

`FormData` expects an actual form element or another supported source. If `querySelector()` returns `null`, the constructor fails.

**Problem:** This code tries to create `FormData` before confirming that the form exists, which can lead to a runtime error such as `Failed to construct 'FormData': parameter 1 is not of type 'HTMLFormElement'`.

```javascript
const form = document.querySelector("#signup-form");
const formData = new FormData(form);
```

**Fix:** Check for the element first before passing it into `FormData`.

```javascript
const form = document.querySelector("#signup-form");

if (form) {
  const formData = new FormData(form);
  console.log(formData.get("email"));
}
```

The fix works because the constructor only runs when a valid form element is present.

### Mistake 3: Expecting repeated query keys to behave like arrays automatically

Query strings can contain the same key more than once, but `get()` returns only the first value. If you expect every value, you must ask for them explicitly.

**Problem:** This code assumes a single value for `tag`, but the URL may contain `tag=js&tag=dom&tag=api`.

```javascript
const params = new URLSearchParams("tag=js&tag=dom&tag=api");
const tag = params.get("tag");
```

**Fix:** Use `getAll()` when a key may appear multiple times.

```javascript
const params = new URLSearchParams("tag=js&tag=dom&tag=api");
const tags = params.getAll("tag");

console.log(tags); // ["js", "dom", "api"]
```

Output (tested with Node 24.21.0):

```text
[ "js", "dom", "api" ]
```

The corrected version works because it collects every matching value instead of discarding the extras.

## 7. Best Practices

### Practice 1: Use `URL` as the main entry point

Even if you only care about the query string, starting with `URL` is often the safest approach because it keeps the full address intact.

```javascript
const url = new URL(window.location.href);
url.searchParams.set("page", "3");
```

This is better than reconstructing the URL yourself because it preserves the origin, path, and fragment.

### Practice 2: Prefer `set()` for single-value keys

If a key should appear only once, use `set()` instead of `append()`. That keeps the data predictable.

```javascript
const params = new URLSearchParams();
params.set("sort", "price");
params.set("sort", "rating");
```

The second call replaces the first one, which is what you want for a single-value field.

### Practice 3: Convert form data deliberately

Use `FormData` when the form payload should stay in its native format, and convert to `URLSearchParams` only when you truly need a query string.

```javascript
const formData = new FormData(document.querySelector("form"));
const params = new URLSearchParams(formData);
```

This keeps your intent clear and helps you choose between GET-style URLs and POST-style bodies.

## 8. Limitations and Edge Cases

- `URL` parsing requires a valid absolute URL in many cases, especially outside the browser location context.
- `URLSearchParams` preserves repeated keys, but order matters if the server expects parameters in a certain sequence.
- `FormData` includes file inputs as `File` objects, which do not behave like plain strings.
- Disabled form controls are not included in `FormData`, which can surprise beginners.
- Unchecked checkboxes and radio buttons are omitted entirely, so missing keys may be normal rather than an error.
- Spaces in serialized query strings are encoded by the browser, so the output may look different from the input text.

> A common `"not working"` report is expecting every form field to appear in `FormData`. Disabled fields, unchecked boxes, and buttons are intentionally excluded.

## 9. Practical Mini Project

In this mini project, you will build a simple search form that updates the browser URL without reloading the page and keeps the form in sync with the current query string.

```html
<form id="product-search">
  <label for="query">Search</label>
  <input type="text" id="query" name="q">

  <label for="sort">Sort</label>
  <select id="sort" name="sort">
    <option value="popular">Popular</option>
    <option value="price">Price</option>
  </select>

  <button type="submit">Apply</button>
</form>

<script>
  const form = document.querySelector("#product-search");
  const queryInput = document.querySelector("#query");
  const sortSelect = document.querySelector("#sort");

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

  queryInput.value = params.get("q") || "";
  sortSelect.value = params.get("sort") || "popular";

  form.addEventListener("submit", function (event) {
    event.preventDefault();

    const formData = new FormData(form);
    const nextUrl = new URL(window.location.href);

    nextUrl.search = new URLSearchParams(formData).toString();
    window.history.replaceState({}, "", nextUrl);
  });
</script>
```

This example shows the whole workflow: read current params, initialize the form, convert form values into search params, and update the URL without reloading the page.

## 10. Key Points

- `URL` handles the full address, not just the query string.
- `URLSearchParams` is the best tool for reading and writing `?key=value` data.
- `FormData` is the browser-native representation of form input values.
- Use `get()` for one value and `getAll()` for repeated keys.
- Let the browser handle encoding instead of concatenating query strings manually.
- Check for missing form elements before creating `FormData`.

## 11. Practice Exercise

Use this exercise to test whether you can read and modify query strings and form data together.

- Create a page with a form containing a search field and a category dropdown.
- When the page loads, read `q` and `category` from the URL and fill the form.
- On submit, prevent navigation and update the current URL with the form values.
- Make sure spaces and special characters are encoded correctly.

**Expected output:** After submitting the form, the URL should look like `/products?q=blue+shirt&category=clothing` or an equivalent encoded version, and the form should keep those values on refresh.

**Hint:** Build a `URL` object from `window.location.href`, then use `searchParams` and `FormData` together.

**Solution:**

```javascript
const form = document.querySelector("#filter-form");
const queryInput = document.querySelector("#q");
const categorySelect = document.querySelector("#category");

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

queryInput.value = url.searchParams.get("q") || "";
categorySelect.value = url.searchParams.get("category") || "all";

form.addEventListener("submit", function (event) {
  event.preventDefault();

  const formData = new FormData(form);
  const nextUrl = new URL(window.location.href);

  nextUrl.search = new URLSearchParams(formData).toString();
  window.history.replaceState({}, "", nextUrl);
});
```

This solution works because it keeps the URL and the form synchronized using browser-native parsing and serialization.

## 12. Final Summary

`URL`, `URLSearchParams`, and `FormData` are core browser APIs for working with addresses, query strings, and form values. They help you avoid fragile string manipulation and make your code easier to read and maintain.

Use `URL` when you need the whole address, `URLSearchParams` when you need to inspect or change query parameters, and `FormData` when you need to collect or send form input. Once you understand how they fit together, you can build cleaner search pages, shareable filters, and reliable form submissions.

Next, practice converting a real form into query parameters and back again. That exercise will make the relationship between these APIs feel natural.