Understanding UTF-8 and Base64 Compatibility

A common frustration for developers working with Base64 in the browser is the sudden appearance of garbled text (like é) or outright application crashes when dealing with Emojis, accented characters, or non-Latin alphabets.

The root cause lies in how Base64 interacts with different character encoding standards, specifically the collision between Latin1 (ISO-8859-1) and UTF-8.

The Problem: The Browser's btoa() Limitation

The native browser functions for Base64 are btoa() (binary to ASCII) and atob() (ASCII to binary).

These functions were designed decades ago and strictly operate on 8-bit bytes (Latin1). If you attempt to pass a string containing a multi-byte UTF-8 character (like a Japanese kanji or an Emoji) into btoa(), the browser will throw a fatal error:

// Attempting to encode an emoji
btoa("👋");

// Uncaught DOMException: Failed to execute 'btoa' on 'Window': 
// The string to be encoded contains characters outside of the Latin1 range.

Why Does This Happen?

JavaScript strings in the browser are represented internally as UTF-16. However, a single Emoji can take up to 4 bytes. btoa() does not know how to break down a UTF-16 JavaScript string into the raw binary bytes required by the Base64 algorithm.

The Modern Solution: TextEncoder and TextDecoder

To safely Base64 encode and decode UTF-8 text, you must explicitly translate the JavaScript string into a raw byte array (Uint8Array) before applying the Base64 transformation.

Modern browsers provide the TextEncoder and TextDecoder APIs to do exactly this.

Safely Encoding UTF-8 to Base64

function encodeBase64UTF8(text) {
    // 1. Convert the JS string to a raw UTF-8 byte array
    const bytes = new TextEncoder().encode(text);
    
    // 2. Convert the byte array into a Latin1 string
    let binaryString = "";
    for (let i = 0; i < bytes.length; i++) {
        binaryString += String.fromCharCode(bytes[i]);
    }
    
    // 3. Base64 encode the Latin1 string
    return btoa(binaryString);
}

console.log(encodeBase64UTF8("こんにちは")); // Japanese for Hello
// Output: 44GT44KT44Gr44Gh44Gv

Safely Decoding Base64 to UTF-8

When you receive a Base64 string from a server (which was likely generated from UTF-8 bytes), you must reverse the process:

function decodeBase64UTF8(base64) {
    // 1. Decode Base64 to a Latin1 binary string
    const binaryString = atob(base64);
    
    // 2. Convert the binary string to a raw byte array
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
        bytes[i] = binaryString.charCodeAt(i);
    }
    
    // 3. Decode the raw bytes into a UTF-8 JS String
    return new TextDecoder('utf-8').decode(bytes);
}

console.log(decodeBase64UTF8("44GT44KT44Gr44Gh44Gv")); 
// Output: こんにちは

How Server-Side Languages Handle This

Languages like Java, Python, Go, and Node.js handle this much more gracefully because their standard libraries force the developer to explicitly request a byte conversion before calling the Base64 functions.

• Java: new String(bytes, StandardCharsets.UTF_8)
• Python: string.encode('utf-8')
• Node.js: Buffer.from(string, 'utf-8')

The Legacy Solution: encodeURIComponent

Before TextEncoder was widely supported, developers used a hack involving encodeURIComponent and escape to force the browser to convert multi-byte characters into URI-escaped single bytes before passing them to btoa().

While this works, it is mathematically slower and highly discouraged in modern web development. Always prefer the TextEncoder APIs.

Conclusion

If you are building web applications that handle internationalization, user-generated content, or Emojis, you must not use atob() and btoa() directly on raw text. By properly marshaling your strings into Uint8Array buffers first, you ensure 100% compatibility across all languages and platforms.

Our Base64 Decoder uses this exact robust TextDecoder strategy, guaranteeing that any UTF-8 payload you paste into it will render flawlessly.