PlayTools

Base64 and URL Encoding: When to Use Which

Developers · Updated November 5, 2026 · 4 min read

Developers reach for Base64 when they need to move binary data through text-only channels — embedding a small image in CSS, serializing a blob in localStorage, or building a data: URL. URL encoding (percent-encoding) solves a different problem: making arbitrary strings safe in query parameters and form posts. Confusing the two produces subtle bugs: double-encoded query strings, broken plus signs in phone numbers, and “encrypted” passwords that are only encoded.

Base64 in plain language

Base64 maps every three bytes to four printable ASCII characters. It is reversible and offers no confidentiality — anyone can decode it. Use it for transport, not security. When you need secrecy, use TLS in transit and proper encryption at rest with keys you control.

Standard Base64 uses + and /, which are reserved in URLs. Base64url replaces them with - and _ and often omits padding = characters. JWTs and many APIs use base64url; generic atob() in the browser expects standard Base64 with padding restored.

URL encoding (percent-encoding)

Reserved characters in URLs — space, &, =, ?, #, non-ASCII letters — must be escaped as %XX hex bytes. encodeURIComponent escapes everything except A-Z a-z 0-9 - _ . ! ~ * ' ( ). encodeURI is looser and keeps : / ? # [ ] @ for full URLs.

HTML entity encoding (&, <) is yet a third scheme, for document text rather than URLs. Use the HTML encoder when inserting user content into templates, not when building fetch URLs.

const q = "café & résumé";
encodeURIComponent(q); // "caf%C3%A9%20%26%20r%C3%A9sum%C3%A9"
// Wrong for a full URL path segment if you encode twice.

Double-encoding bugs

  • Frameworks often encode form fields automatically; manually wrapping values in encodeURIComponent before passing to fetch can encode % as %25.
  • Plus signs in query strings historically meant space; some servers still treat + as space. Use %20 for spaces in query values when in doubt.
  • Slashes in Base64 standard alphabet break path routing if pasted raw into a URL — prefer base64url for tokens in paths.

Hashes are not encodings

SHA-256 and friends produce fixed-length digests that cannot be reversed. They are for integrity and password verification (with salt and slow algorithms like bcrypt on servers), not for transporting data. Do not “hash” a password with Base64 and call it secure.

When comparing file checksums, hex encoding of the digest is conventional; Base64 of the raw bytes is also valid but less common in CLI tools.

Practical recipes

  1. Embed a small icon: convert PNG to Base64 data URL in CSS background-image — keep under a few KB.
  2. Build a search URL: encodeURIComponent each parameter value; join with &.
  3. Debug an API 400: decode JWT payload locally; re-encode query params one layer at a time until the server accepts.
  4. Store binary in JSON: Base64 string field, document max size limits in your API contract.

Unicode and international text

URL encoding operates on UTF-8 bytes. The path /café may appear as /caf%C3%A9 or as punycode for domain names (xn--). Normalise Unicode before comparing strings — NFC versus NFD can produce different encodings for visually identical URLs.

Base64 encodes bytes, not characters. UTF-8 text must be encoded to bytes first; decoding with the wrong charset produces mojibake. When exchanging files internationally, state charset=utf-8 in JSON and Content-Type headers explicitly.

Performance and size

Base64 expands binary size by roughly 33%. For images on the web, prefer actual image URLs with caching headers instead of giant data URLs in HTML. For API payloads, attach binary as multipart/form-data when sizes exceed a few kilobytes.

Percent-encoding can inflate query strings — a long filter expression may hit URL length limits in older browsers and proxies (often 2–8 KB). Use POST with a JSON body for complex queries instead of encoding them entirely in the query string.

Testing encoders in CI

  • Golden vectors: known string → expected Base64 and back without loss.
  • Round-trip URL params used in deep links shared by email clients.
  • Reject non-base64url characters in token parsers before calling crypto libraries.
  • Snapshot HTML entity output for XSS regression tests on user-generated content.

The Base64, URL encoder, and HTML encoder tools on PlayTools mirror browser standards — use them to reproduce customer reports before you patch production services.

Common API patterns

OAuth redirects append state and code query parameters — both must be URL-encoded and verified on return. OpenID Connect id_tokens are JWTs using base64url segments; treat them like any other encoded token.

GraphQL often POSTs JSON bodies instead of long query strings, which avoids URL length limits but still requires correct JSON syntax in the variables object.

Webhooks that sign payloads may send HMAC hex digests in headers while the body remains raw JSON — do not base64 the whole request when verifying signatures.

Choosing tools on this site

Use the Base64 encoder when you have binary or UTF-8 text and need a safe ASCII representation. Switch to the URL encoder when building query strings for links users will click. The HTML encoder is for inserting untrusted text into HTML templates — not for JSON inside script tags, where JSON.stringify is the correct tool.

If you are unsure which layer failed, decode step by step: URL-decode the query string, then parse JSON, then Base64-decode embedded fields. Each layer should produce readable structure before you move to the next.

Document encoding expectations in your API README so client authors do not guess — especially for fields that are binary, hexadecimal, or base64url.

Tools used in this guide