decodeURIComponent()

decodeURIComponent(encodedURIComponent)

Returns string· Added in vES1· Updated June 1, 2026· Global Functions

javascriptdecodeuricomponenturiencodingurl

The decodeURIComponent() function decodes a URI component that was encoded with encodeURIComponent(). Unlike decodeURI(), this function decodes all special characters including reserved characters like ?, #, /, and &.

Syntax

decodeURIComponent(encodedURIComponent)

Parameters

Parameter	Type	Description
`encodedURIComponent`	string	An encoded URI component.

Return Value

A new decoded string.

What decodeURIComponent() Decodes

This function decodes everything that encodeURIComponent() encodes, including characters that have structural meaning in URLs. Spaces become %20, slashes become %2F, the question mark becomes %3F, and the equals sign becomes %3D. Running decodeURIComponent() on any of these sequences restores the original character. The following three calls show a space, a path-like fragment with query delimiters, and an email address — all round-tripped through encoding and back:

decodeURIComponent("hello%20world");
// "hello world"

decodeURIComponent("a%2Fb%3Fc%3Dd");
// "a/b?c=d"

decodeURIComponent("test%40example.com");
// "test@example.com"

Examples

The examples below show common patterns for using decodeURIComponent() in real code. Each pattern addresses a different kind of encoded input: query strings, path segments, and structured data returned by an API.

Decoding query parameters

// When you receive encoded query parameters
const queryString = "q%3Dhello%20world%26lang%3Den";
decodeURIComponent(queryString);
// "q=hello world&lang=en"

// Using with URLSearchParams
const params = new URLSearchParams("q=hello%20world");
params.get("q");
// "hello world"

Query parameters are the most common place you will reach for decodeURIComponent(). The function restores the raw value from its percent-encoded form so you can work with the original string. When the query string contains multiple parameters separated by & and =, decoding the full string recovers those delimiters alongside the values.

Decoding path segments

const encodedPath = "my%20document.pdf";
decodeURIComponent(encodedPath);
// "my document.pdf"

Path segments are simpler than query parameters because they typically contain a single encoded value with no internal structure. Decoding is a one-step operation that recovers the original filename or path component. What looks like my%20document.pdf in a URL becomes the human-readable my document.pdf after the call.

Decoding API responses

// When an API returns encoded data
const apiData = "%7B%22name%22%3A%22John%22%2C%22age%22%3A30%7D";
decodeURIComponent(apiData);
// "{\"name\":\"John\",\"age\":30}"

Sometimes you receive encoded data from an API rather than from a URL — a JSON payload that was percent-encoded for transport. decodeURIComponent() restores the original JSON string so you can hand it to JSON.parse(). This is a common pattern when working with older APIs that encode their responses for safe embedding inside query parameters or form bodies.

decodeURI vs decodeURIComponent

The key difference is what each function decodes:

// decodeURI preserves certain characters
decodeURI("%3F%26");
// "?&" - question mark and ampersand preserved

// decodeURIComponent decodes everything
decodeURIComponent("%3F%26");
// "?&" - decodes everything

// Example with slashes
decodeURI("%2F");
// "/" - preserved

decodeURIComponent("%2F");
// "/" - decoded

When to use each:

Use Case	Function
Decoding a full URI	`decodeURI()`
Decoding query parameter values	`decodeURIComponent()`
Decoding path segments	`decodeURIComponent()`
Decoding any encoded component	`decodeURIComponent()`

Common Mistakes

Using decodeURI for query parameter values

// URL with query string
const url = "https://example.com/search?q=hello%20world";

// Using decodeURI on full URL - not ideal
decodeURI(url);
// "https://example.com/search?q=hello world" - works but not recommended

// Correct approach - extract and decode the component
const urlObj = new URL(url);
urlObj.searchParams.get("q");
// "hello world"

A related mistake is forgetting that a query string value arrived encoded and trying to use it directly. The raw url.search property returns the encoded form, so you need an explicit decoding step. The URLSearchParams API handles this for you, but when you split the string manually you must call decodeURIComponent() on each extracted value.

Not handling encoding at all

// DON'T - access the raw encoded value
const rawQuery = url.search;
// "q=hello%20world"

// DO - use URLSearchParams or decodeURIComponent
const query = decodeURIComponent(url.search.split("=")[1]);
// "hello world"

How it differs from decodeURI()

decodeURIComponent() decodes percent-encoded sequences for all characters except the handful that are unreserved in all URI contexts: A–Z, a–z, 0–9, -, _, ., !, ~, *, ', (, ). In contrast, decodeURI() also preserves the structural characters of a complete URI — such as /, ?, #, &, =, and : — which have special meaning at the top level of a URL. Use decodeURIComponent() on individual values like query parameter values or path segments; use decodeURI() on a complete URL string.

Error handling

decodeURIComponent() throws a URIError if the encoded string contains a malformed percent-encoded sequence — for example, % not followed by two valid hex digits, or a sequence representing a lone surrogate that cannot be decoded as valid UTF-8. Because user-supplied URLs or query strings may be incomplete or corrupted, always wrap calls in a try/catch when processing untrusted input:

function safeDecodeComponent(str) {
  try {
    return decodeURIComponent(str);
  } catch {
    return str;
  }
}

Modern alternative: URLSearchParams

For working with query strings in the browser or Node.js, URLSearchParams is often cleaner than calling decodeURIComponent manually. You construct it with a query string and then read individual parameters with get(). The class handles both encoding on the way in and decoding on the way out, so you never touch percent sequences directly. This is especially useful when you need to extract one or two values from a longer query string without parsing the whole thing yourself:

const params = new URLSearchParams('q=hello%20world&page=2');
params.get('q');    // 'hello world' — decoded automatically
params.get('page'); // '2'

Use decodeURIComponent directly when you are working with raw encoded strings outside of a URL context, or when you need to decode a specific segment before parsing.

When decodeURIComponent() is the right tool

Use decodeURIComponent() any time you are handling a single encoded piece of data rather than a full URL. Query values, path segments, and form-style fragments are all common fits. The function is strict by design, which is helpful because it catches malformed input instead of silently guessing. That makes it a good match for code that needs to distinguish valid encoded data from corrupted or incomplete strings.