URL Encode Square Brackets ([ ])

Square brackets ([ and ]) are reserved characters in URLs, primarily designated for IPv6 address literals in the host component. When used as data in path segments or query parameters, they should be encoded as %5B and %5D respectively.

Percent-encoded forms:

• [ encodes to %5B (ASCII code 91, hexadecimal 0x5B)
• ] encodes to %5D (ASCII code 93, hexadecimal 0x5D)

Square brackets in practice: Despite technically requiring encoding, square brackets are widely used unencoded in query parameters to represent arrays, especially in PHP and Ruby on Rails conventions: ?colors[]=red&colors[]=blue. Most web servers and frameworks accept this, but it is not standards-compliant.

JavaScript behavior:

encodeURIComponent("[0]")               // "%5B0%5D"
encodeURIComponent("colors[]")          // "colors%5B%5D"
encodeURI("?items[0]=a&items[1]=b")    // "?items%5B0%5D=a&items%5B1%5D=b"

// Note: encodeURI DOES encode brackets (they're not structural in URIs)

Array parameter conventions: Different frameworks handle arrays in query strings differently:

• PHP/Rails style: ?tags[]=js&tags[]=ts (brackets indicate array)
• Repeated keys: ?tags=js&tags=ts (same key repeated)
• Comma-separated: ?tags=js,ts (single value, comma-delimited)
• Indexed: ?tags[0]=js&tags[1]=ts (explicit indices)

The bracket convention is so common that many HTTP client libraries (like Axios and jQuery) generate bracket-style array parameters by default, even though they technically need encoding.

Common scenarios:

• API query parameters that accept arrays or nested objects
• Elasticsearch query DSL parameters
• Filter syntax in REST APIs: ?filter[status]=active&filter[role]=admin
• JSON Pointer references: /data/items/[0]/name

Pitfall: Some proxies, CDNs, and load balancers strip or reject URLs containing unencoded square brackets. If your API uses bracket notation in query parameters and users report intermittent failures, check whether intermediate infrastructure is modifying the URL. Encoding brackets as %5B and %5D is the safest approach for maximum compatibility.