DEV Community: MOUSTAID Hamza

How to Encode Base64 in JavaScript Without Breaking Unicode

MOUSTAID Hamza — Fri, 24 Apr 2026 11:17:44 +0000

Base64 encoding is one of those small developer tasks that looks simple until you hit Unicode characters, files, APIs, or URL-safe formats.

In JavaScript, many tutorials show this:

btoa("Hello World");

And yes, it works.

But only for simple ASCII text.

Once you try to encode something like:

"Café 🚀"

you may run into errors or broken output.

In this guide, we’ll cover how Base64 encoding works in JavaScript, when btoa() is enough, when it is not, and how to encode text, Unicode, files, images, and URL-safe Base64 correctly.

You can also test examples quickly with EncodingBase64, a free browser-based Base64 encoder for text, files, images, URL-safe Base64, hex, and URL encoding.

What is Base64 encoding?

Base64 is a way to represent binary data using readable ASCII characters.

It is commonly used when binary data needs to travel through systems that expect text, such as:

APIs
JSON payloads
email attachments
HTML/CSS data URIs
authentication headers
embedded images
configuration files

For example:

Hello World

becomes:

SGVsbG8gV29ybGQ=

Base64 does not encrypt data. Anyone can decode it.

It only changes the representation of the data.

Basic Base64 encoding with btoa()

JavaScript includes a built-in function called btoa().

Example:

const text = "Hello World";
const encoded = btoa(text);

console.log(encoded);
// SGVsbG8gV29ybGQ=

To decode it back:

const decoded = atob(encoded);

console.log(decoded);
// Hello World

This is fine for basic ASCII strings.

But there is a problem.

The Unicode problem with btoa()

Try this:

const text = "Café 🚀";
const encoded = btoa(text);

console.log(encoded);

Depending on the environment, you may get an error like:

InvalidCharacterError

Why?

Because btoa() expects a binary string where each character is in the Latin-1 range. It does not directly support full Unicode text.

Modern apps often deal with:

accented characters
Arabic
French
Spanish
German
Portuguese
emojis
non-Latin scripts

So we need a safer method.

Unicode-safe Base64 encoding

Use TextEncoder to convert the string into UTF-8 bytes first.

function encodeBase64Unicode(text) {
  const bytes = new TextEncoder().encode(text);

  let binary = "";
  bytes.forEach((byte) => {
    binary += String.fromCharCode(byte);
  });

  return btoa(binary);
}

console.log(encodeBase64Unicode("Café 🚀"));
// Q2Fmw6kg8J+agA==

Now the Unicode string is safely converted to UTF-8 before Base64 encoding.

Unicode-safe Base64 decoding

To decode it back properly, use TextDecoder.

function decodeBase64Unicode(base64) {
  const binary = atob(base64);

  const bytes = Uint8Array.from(binary, (char) => {
    return char.charCodeAt(0);
  });

  return new TextDecoder().decode(bytes);
}

const encoded = encodeBase64Unicode("Café 🚀");
const decoded = decodeBase64Unicode(encoded);

console.log(decoded);
// Café 🚀

This is safer for real-world text.

Encoding a file to Base64 in JavaScript

For files, you can use FileReader.

Example with an HTML file input:

<input type="file" id="fileInput" />

const input = document.getElementById("fileInput");

input.addEventListener("change", () => {
  const file = input.files[0];

  if (!file) return;

  const reader = new FileReader();

  reader.onload = () => {
    console.log(reader.result);
  };

  reader.readAsDataURL(file);
});

The result will look like this:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

This is called a data URI.

It includes:

data:[mime-type];base64,[base64-data]

For example:

data:image/png;base64,iVBORw0KGgo...

If you only want the raw Base64 part, remove everything before the comma:

const dataUrl = reader.result;
const rawBase64 = dataUrl.split(",")[1];

console.log(rawBase64);

Encoding an image to Base64

Images are one of the most common Base64 use cases.

You might encode images to Base64 when:

embedding a tiny icon in HTML
storing a small image in JSON
sending an image through an API
generating previews
creating CSS background images

Example HTML output:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="Example" />

Example CSS output:

.icon {
  background-image: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...");
}

This is useful for small images.

But be careful: Base64 increases file size, so it is usually not ideal for large images.

For quick browser-based image conversion, EncodingBase64’s Image to Base64 tool can convert images into raw Base64, data URI, HTML, CSS, or Markdown formats.

What is URL-safe Base64?

Standard Base64 uses characters like:

+
/
=

These characters can be problematic in URLs.

URL-safe Base64 replaces:

+ with -
/ with _

Padding = may also be removed in some systems.

Example helper:

function toBase64Url(base64) {
  return base64
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/g, "");
}

const encoded = encodeBase64Unicode("Hello World");
const urlSafe = toBase64Url(encoded);

console.log(urlSafe);
// SGVsbG8gV29ybGQ

To convert Base64URL back to standard Base64:

function fromBase64Url(base64Url) {
  let base64 = base64Url
    .replace(/-/g, "+")
    .replace(/_/g, "/");

  while (base64.length % 4 !== 0) {
    base64 += "=";
  }

  return base64;
}

Base64URL is commonly used in:

JWTs
URL tokens
authentication flows
compact identifiers
web-safe encoded data

Common Base64 encoding mistakes

1. Thinking Base64 is encryption

Base64 is not secure. It is reversible.

Do not use it to protect passwords, API keys, or private data.

2. Using btoa() directly with Unicode

This can break:

btoa("Café 🚀");

Use TextEncoder instead.

3. Using standard Base64 in URLs

Standard Base64 can contain +, /, and =. Use Base64URL when the value needs to go inside a URL.

4. Encoding large images unnecessarily

Base64 is usually better for small assets, not large files.

5. Forgetting the MIME type for images

For browser display, this:

iVBORw0KGgo...

may not be enough.

You often need:

data:image/png;base64,iVBORw0KGgo...

Quick answer

Use btoa() only for simple ASCII text.

For Unicode-safe Base64 encoding in JavaScript, convert text to UTF-8 bytes first using TextEncoder, then encode those bytes with btoa().

For files and images, use FileReader.readAsDataURL().

For URLs, convert standard Base64 into Base64URL by replacing + with -, / with _, and optionally removing = padding.

Final thoughts

Base64 encoding is simple in theory, but real-world usage gets more complex when you deal with Unicode, files, images, URLs, and APIs.

For quick testing, debugging, and conversion, a browser-based tool like EncodingBase64 can save time because you can encode text, files, images, URL-safe Base64, hex, and URLs without setting up code.

The key rule to remember:

Base64 is an encoding format, not a security feature.

Use it when you need text-safe data representation, not when you need encryption.

How to Decode Base64 Safely: Text, Images, Files, and Common Errors

MOUSTAID Hamza — Fri, 24 Apr 2026 11:17:33 +0000

Base64 decoding looks simple.

You take a string like this:

SGVsbG8gV29ybGQ=

Decode it, and get:

Hello World

But in real projects, Base64 decoding can fail for many reasons:

missing padding
invalid characters
Unicode problems
Base64URL format
binary data being treated as text
image data missing a MIME type
whitespace copied into the string

This guide explains how to decode Base64 safely in JavaScript, Python, and the command line, and how to troubleshoot the most common Base64 decoding issues.

You can also test strings quickly with DecodingBase64, a free client-side Base64 decoder that converts Base64 to text, images, hex output, or downloadable files.

What does Base64 decoding do?

Base64 decoding reverses Base64 encoding.

Base64 represents bytes using readable characters. Decoding converts those characters back into the original bytes.

Those bytes may represent:

plain text
JSON
an image
a PDF
a ZIP file
binary data
an API token
a data URI

This is important:

Base64 decoding does not always produce readable text.

Sometimes the decoded output is binary data.

That is why a good decoder should support text, image, file, and hex output.

Basic Base64 decoding in JavaScript

JavaScript provides atob().

const base64 = "SGVsbG8gV29ybGQ=";
const decoded = atob(base64);

console.log(decoded);
// Hello World

This works for simple ASCII text.

But it can break or produce incorrect output with Unicode text.

Unicode-safe Base64 decoding in JavaScript

If the original text contained Unicode characters, you should decode bytes using TextDecoder.

function decodeBase64Unicode(base64) {
  const binary = atob(base64);

  const bytes = Uint8Array.from(binary, (char) => {
    return char.charCodeAt(0);
  });

  return new TextDecoder("utf-8").decode(bytes);
}

console.log(decodeBase64Unicode("Q2Fmw6kg8J+agA=="));
// Café 🚀

This approach is safer for real-world text because it handles UTF-8 correctly.

Decode Base64 in Python

Python has a built-in base64 module.

import base64

encoded = "SGVsbG8gV29ybGQ="
decoded_bytes = base64.b64decode(encoded)
decoded_text = decoded_bytes.decode("utf-8")

print(decoded_text)
# Hello World

For Unicode text:

import base64

encoded = "Q2Fmw6kg8J+agA=="
decoded = base64.b64decode(encoded).decode("utf-8")

print(decoded)
# Café 🚀

If the output is binary, do not decode it as text. Save it as bytes instead.

Decode Base64 from the command line

On macOS and Linux:

echo "SGVsbG8gV29ybGQ=" | base64 --decode

Output:

Hello World

To decode a Base64 file into a binary file:

base64 --decode input.txt > output.bin

For an image:

base64 --decode image-base64.txt > image.png

The correct output extension depends on the original file type.

How to decode a Base64 image

A Base64 image often looks like this:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

This is called a data URI.

It has two important parts:

data:image/png;base64,

and then the Base64 data:

iVBORw0KGgoAAAANSUhEUgAA...

The MIME type tells the browser what kind of file it is:

image/png
image/jpeg
image/webp
image/gif
image/svg+xml

If you only have the raw Base64 string, you may need to know the original MIME type to display or save it correctly.

For image debugging, DecodingBase64’s Base64 to Image tool can turn a Base64 image string back into a preview and downloadable image file.

Base64URL decoding

Some strings are not standard Base64. They are Base64URL.

Base64URL is common in:

JWTs
URL tokens
authentication systems
web-safe identifiers

Standard Base64 uses:

+
/
=

Base64URL may use:

-
_

and often removes padding.

To decode Base64URL in JavaScript, normalize it first:

function base64UrlToBase64(base64Url) {
  let base64 = base64Url
    .replace(/-/g, "+")
    .replace(/_/g, "/");

  while (base64.length % 4 !== 0) {
    base64 += "=";
  }

  return base64;
}

function decodeBase64Url(base64Url) {
  const base64 = base64UrlToBase64(base64Url);
  return atob(base64);
}

console.log(decodeBase64Url("SGVsbG8gV29ybGQ"));
// Hello World

If a standard decoder fails, check whether your string is actually Base64URL.

Common Base64 decoding errors

1. Incorrect padding

Base64 strings often end with:

or:

==

Padding helps make the length valid.

If padding is missing, some decoders fail.

Fix:

function addBase64Padding(base64) {
  while (base64.length % 4 !== 0) {
    base64 += "=";
  }

  return base64;
}

2. Invalid characters

Standard Base64 should usually contain:

A-Z
a-z
0-9
+
/
=

If you see - and _, it may be Base64URL.

If you see spaces, quotes, commas, or copied line breaks, clean the input first.

3. Whitespace problems

Copied Base64 strings may contain line breaks or spaces.

const cleaned = input.replace(/\s/g, "");

4. Decoding binary as text

Not all decoded Base64 is readable.

If the decoded bytes represent an image or file, showing them as text will look broken.

Use a file output, image preview, or hex view instead.

5. Wrong character set

If the decoded text looks strange, it may be a charset issue.

Try UTF-8 first. If that fails, the original data may use another encoding.

Quick answer

To decode Base64 safely:

Clean whitespace.
Detect whether it is standard Base64 or Base64URL.
Add missing padding if needed.
Decode to bytes.
Interpret the bytes correctly as text, image, file, or binary data.

Do not assume every Base64 string is plain text.

Is Base64 secure?

No.

Base64 is not encryption.

Anyone can decode it.

For example:

YXBpX2tleV8xMjM=

decodes to:

api_key_123

So never use Base64 alone to protect sensitive information.

Base64 is useful for representation and transport, not security.

Final thoughts

Base64 decoding is easy when the input is clean ASCII text.

But real-world Base64 often includes images, files, Unicode, Base64URL, missing padding, or binary data.

The safest approach is to decode carefully and inspect the output type.

For fast testing, debugging, and file/image recovery, DecodingBase64 can help because it runs client-side and supports text, image, hex, and file outputs.

Remember:

Base64 decoding gives you bytes. What those bytes mean depends on the original data.

Base64 vs Base64URL vs URL Encoding: When Should You Use Each?

MOUSTAID Hamza — Fri, 24 Apr 2026 11:17:18 +0000

Base64, Base64URL, and URL encoding are often confused because they all seem to “encode” data.

But they solve different problems.

Using the wrong one can break URLs, APIs, JWTs, image data, or browser behavior.

In this guide, we’ll compare:

Base64
Base64URL
URL encoding / percent encoding

You’ll learn what each one does, where each one is useful, and how to choose the right format.

For quick testing, you can use EncodingBase64 for Base64, Base64URL, URL encoding, hex, and image-to-Base64 conversions. If you need to reverse Base64 back into text, images, or files, DecodingBase64 is the matching decoder.

Quick answer

Use Base64 when you need to represent binary data as text.

Use Base64URL when Base64 data must safely appear inside URLs, JWTs, or URL tokens.

Use URL encoding when you need to safely place normal text inside a URL query string or path.

They are not interchangeable.

What is Base64?

Base64 converts bytes into readable ASCII characters.

Example:

Hello World

becomes:

SGVsbG8gV29ybGQ=

Base64 is commonly used for:

sending binary data in JSON
embedding small images
email attachments
API payloads
data URIs
basic text-safe representation

Base64 uses characters like:

A-Z
a-z
0-9
+
/
=

The = character is padding.

When to use Base64

Use Base64 when the original data is binary or byte-based but needs to be represented as text.

Good use cases include:

1. Embedding small images

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." />

2. Sending binary data in JSON

{
  "filename": "avatar.png",
  "content": "iVBORw0KGgoAAAANSUhEUgAA..."
}

3. Encoding small files for transport

Some APIs accept file content as Base64 strings.

4. Encoding credentials in specific protocols

Basic authentication uses Base64 representation for:

username:password

But remember: this is not secure by itself. It must be used over HTTPS.

When not to use Base64

Do not use Base64 for:

encryption
password protection
hiding secrets
large images when normal files work better
URL parameters without URL-safe conversion

Base64 increases data size, often by about one-third.

That is acceptable in many cases, but not always ideal.

What is Base64URL?

Base64URL is a URL-safe version of Base64.

Standard Base64 may contain:

+
/
=

These characters can cause issues in URLs.

Base64URL replaces:

+ with -
/ with _

Padding = is often removed.

Example standard Base64:

SGVsbG8+V29ybGQ/

Base64URL version:

SGVsbG8-V29ybGQ_

Base64URL is common in:

JWTs
URL-safe tokens
password reset links
email verification links
OAuth flows
compact identifiers

Why standard Base64 can break in URLs

Imagine this Base64 string:

abc+def/ghi==

If placed directly inside a URL:

https://example.com/?token=abc+def/ghi==

The + may be interpreted as a space in some URL contexts.

The / may be interpreted as a path separator.

The = can interfere with query parsing.

That is why Base64URL exists.

A safer token would look like:

abc-def_ghi

Base64URL helper in JavaScript

Convert standard Base64 to Base64URL:

function toBase64Url(base64) {
  return base64
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/g, "");
}

Convert Base64URL back to standard Base64:

function fromBase64Url(base64Url) {
  let base64 = base64Url
    .replace(/-/g, "+")
    .replace(/_/g, "/");

  while (base64.length % 4 !== 0) {
    base64 += "=";
  }

  return base64;
}

Example:

const base64 = "SGVsbG8gV29ybGQ=";
const base64Url = toBase64Url(base64);

console.log(base64Url);
// SGVsbG8gV29ybGQ

What is URL encoding?

URL encoding, also called percent encoding, is different from Base64.

It makes text safe for URLs by replacing unsafe characters with % followed by hexadecimal values.

Example:

hello world

becomes:

hello%20world

Another example:

email@example.com

becomes:

email%40example.com

In JavaScript, you can use:

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

For a full URL, you may use:

encodeURI("https://example.com/search?q=hello world");
// https://example.com/search?q=hello%20world

encodeURI vs encodeURIComponent

These two are often confused.

encodeURI()

Use it for a full URL:

encodeURI("https://example.com/search?q=hello world");

It keeps URL structure characters like:

:
/
?
&
=

encodeURIComponent()

Use it for a URL parameter value:

const query = encodeURIComponent("hello world & coffee");
const url = `https://example.com/search?q=${query}`;

console.log(url);
// https://example.com/search?q=hello%20world%20%26%20coffee

Most of the time, if you are encoding a query parameter value, use encodeURIComponent().

Base64 vs URL encoding

Here is the key difference:

Feature	Base64	URL Encoding
Main purpose	Represent bytes as text	Make URL text safe
Used for binary data	Yes	No
Used for query params	Not directly	Yes
Output style	`SGVsbG8=`	`hello%20world`
Reversible	Yes	Yes
Security feature	No	No

If you want to encode an image, use Base64.

If you want to safely put a search query inside a URL, use URL encoding.

Base64URL vs URL encoding

Base64URL is still Base64.

It is designed to make Base64 output safe for URLs.

URL encoding is designed to make normal text safe for URLs.

Example:

Original text:

Hello World

Base64:

SGVsbG8gV29ybGQ=

Base64URL:

SGVsbG8gV29ybGQ

URL encoded:

Hello%20World

They look different because they solve different problems.

Real-world examples

Example 1: API file upload

You have image bytes and need to send them in JSON.

Use Base64.

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Example 2: JWT token

JWTs use Base64URL.

A JWT looks like:

header.payload.signature

Each part is Base64URL encoded.

Example 3: Search query

You want a URL like:

https://example.com/search?q=coffee & tea

Use URL encoding:

https://example.com/search?q=coffee%20%26%20tea

Example 4: Small inline SVG or PNG

Use Base64 or URL-encoded SVG depending on the case.

For small PNG/JPEG/WebP assets, Base64 is common.

For SVG, URL encoding can sometimes be more readable and efficient.

Common mistakes

Mistake 1: Using Base64 as encryption

Base64 can be decoded by anyone.

It does not protect data.

Mistake 2: Putting standard Base64 directly in URLs

Characters like +, /, and = can cause issues.

Use Base64URL or URL encode the value.

Mistake 3: Using URL encoding for binary files

URL encoding is not designed for raw binary file representation.

Use Base64 instead.

Mistake 4: Forgetting to decode in the right order

If data is URL encoded and Base64 encoded, the order matters.

For example:

URL decode
Base64 decode

or the reverse, depending on how the data was originally encoded.

Mistake 5: Not handling Unicode

JavaScript’s btoa() and atob() are not always Unicode-safe by themselves.

Use TextEncoder and TextDecoder when working with modern text.

Which one should you choose?

Use this simple rule:

Situation	Use
Encode text or binary as ASCII	Base64
Put Base64 safely in a URL	Base64URL
Encode a URL query parameter	URL encoding
Encode an image as text	Base64
Encode a JWT payload	Base64URL
Encode spaces and symbols in URLs	URL encoding
Hide sensitive data	None of these

For sensitive data, use proper encryption, hashing, HTTPS, and secure storage depending on the use case.

Final thoughts

Base64, Base64URL, and URL encoding are all useful, but they are not the same.

Base64 helps represent bytes as text.

Base64URL makes Base64 safer for URLs and tokens.

URL encoding makes normal URL text safe.

When debugging encoded data, first identify what kind of encoding you are dealing with. Then choose the right tool or function.

For browser-based testing, EncodingBase64 is useful for encoding workflows like Base64, Base64URL, URL encoding, image to Base64, and hex. For reverse workflows, DecodingBase64 helps decode Base64 back into text, images, hex, or files.

The main thing to remember:

Encoding is about representation. It is not the same as encryption.