← Guides

Developer Guide

Base64 Encoding in JavaScript

btoa and atob are Latin-1 only. Encode UTF-8 with TextEncoder, use Buffer in Node, switch to URL-safe when + and / would break a query, and check results in the browser.

btoa atob unicodetextencoder base64buffer toString base64base64url javascriptdata uri base64

btoa and atob look like a complete Base64 API until the first non-Latin-1 character arrives. btoa('hello') returns aGVsbG8=. atob('SGVsbG8gV29ybGQh') returns Hello World!. btoa('नमस्ते') throws InvalidCharacterError, because those functions treat each code unit as a byte in the 0–255 range, not as UTF-8 text.

That trap is a browser quirk, not a property of the alphabet. Encode to UTF-8 first: TextEncoder produces bytes, you turn those bytes into a binary string, then btoa maps them. Node skips the dance — Buffer.from(s).toString('base64') already uses UTF-8. This page stays on JavaScript: browser, Node, URL-safe alphabets, and data URIs. /tools/base64 is Unicode-safe, has a URL-safe mode, and never uploads the string. Use it to confirm the snippets below. Python’s base64 module is a different guide.

The Latin-1 trap in btoa and atob

btoa(string) means “binary to ASCII.” It reads a JavaScript string as Latin-1: one byte per code unit, values 0–255 only. ASCII hello fits. é (U+00E9) still fits. € (U+20AC) and any emoji do not — the engine throws rather than silently truncating.

atob is the inverse. It returns a binary string of Latin-1 characters, not a UTF-8 JavaScript string. If someone Base64-encoded UTF-8 bytes, atob alone will not reconstruct the original text. Decode those bytes with TextDecoder. Skip deprecated escape / unescape.

btoa('hello');
// 'aGVsbG8='

atob('SGVsbG8gV29ybGQh');
// 'Hello World!'

btoa('€');
// InvalidCharacterError

UTF-8 with TextEncoder, then btoa

The reliable browser pattern is: UTF-8 bytes → binary string → btoa. TextEncoder emits UTF-8. Each byte becomes a code unit with String.fromCharCode, which is exactly the input btoa accepts.

  • toBase64('hello') is still aGVsbG8=.
  • toBase64('👋🌍') is 8J+Ri/CfjI0=.
  • /tools/base64 uses UTF-8 the same way, so the strings match.
function toBase64(text) {
  const bytes = new TextEncoder().encode(text);
  let bin = '';
  for (const b of bytes) bin += String.fromCharCode(b);
  return btoa(bin);
}

function fromBase64(b64) {
  const bin = atob(b64);
  const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

toBase64('नमस्ते');
// '4KSo4KSu4KS44KWN4KSk4KWH'

Node.js Buffer

Node does not ship btoa in older versions, and you should not import a Latin-1 helper when Buffer already does UTF-8 correctly.

Buffer.from(s) without an encoding treats s as UTF-8. Buffer.from(s, 'base64') decodes the alphabet. Prefer utf8 when you decode back to a string. The hello / aGVsbG8= pair is identical to the browser tool.

Buffer.from('hello').toString('base64');
// 'aGVsbG8='

Buffer.from('SGVsbG8gV29ybGQh', 'base64').toString('utf8');
// 'Hello World!'

URL-safe Base64

Standard Base64 uses +, /, and = padding. Those characters are reserved or significant in URLs and filenames. The URL-safe variant maps + → -, / → _, and often drops padding.

<<??>> in standard Base64 is PDw/Pz4+. URL-safe mode on /tools/base64 emits PDw_Pz4- (this input needs no padding). Modern Node has a base64url encoding that matches. In the browser, replace after encoding: + to -, / to _, strip trailing =. Use this alphabet only when the decoder expects it. JWT uses Base64url; a JSON field labelled “base64” usually wants the standard form.

Buffer.from('<<??>>').toString('base64');
// 'PDw/Pz4+'

Buffer.from('<<??>>').toString('base64url');
// 'PDw_Pz4-'

Buffer.from('h').toString('base64url');
// 'aA'  (padding omitted; standard is 'aA==')

Data URIs in the browser

A data URI is data:[mediatype];base64, plus the payload. Images belong on /tools/image-to-base64, which runs FileReader.readAsDataURL in the tab. For a small SVG you already have as text, UTF-8-encode first — the Latin-1 trap applies to SVG source the same way it applies to नमस्ते.

Keep the prefix when you paste into /tools/base64-to-image. That page will not guess a MIME type from raw Base64. /tools/base64 is the right place for Unicode text that is not an image.

Common pitfalls

Calling btoa on user text and catching nothing until production. Mixing URL-safe output with a standard decoder. Double-encoding (Base64 of already Base64). Treating the alphabet as encryption. Copying MIME-wrapped lines (76-character CRLF) into atob without stripping whitespace.

The browser functions are Latin-1. /tools/base64 is UTF-8. If they disagree, the bytes were encoded with the wrong text encoding, not “the wrong Base64.”

  • btoa / atob throw on code points above 255.
  • Node Buffer.from(s).toString('base64') is UTF-8.
  • URL-safe: +/ → -_, padding often omitted.

Worked examples

ASCII hello

Input
hello
Output
aGVsbG8=

Same result from btoa, Buffer.from('hello').toString('base64'), and /tools/base64.

Decode a standard payload

Input
SGVsbG8gV29ybGQh
Output
Hello World!

Paste the input into /tools/base64 in decode mode. atob works here because the original text was ASCII.

URL-safe alphabet

Input
<<??>>
Output
PDw_Pz4-

Standard encoding of the same bytes is PDw/Pz4+. Enable URL-safe mode on /tools/base64.

Frequently asked questions

Why does btoa throw on emoji?

Emoji sit above U+00FF. btoa only accepts Latin-1 code units. Encode with TextEncoder first, or use /tools/base64, which is UTF-8.

Does Node Buffer match the browser tool?

Yes for UTF-8 text: Buffer.from(s).toString('base64') matches /tools/base64. btoa matches only when every character is Latin-1.

When should I use URL-safe Base64?

When the string will sit in a URL, filename, or JWT. Recipients must expect - _ and missing padding. Otherwise keep + / =.

Is the string uploaded?

No. /tools/base64 and /tools/image-to-base64 run in your tab. There is no encode API on thedevtools.in.

Is Base64 encryption?

No. aGVsbG8= is hello in another alphabet. Anyone who can read the string can decode it.

Summary

Treat btoa as a Latin-1 converter, not a Unicode one. UTF-8-encode with TextEncoder in the browser, use Buffer.from(s).toString('base64') in Node, and switch to URL-safe only when the other side asked for it. Confirm hello → aGVsbG8= and <<??>> → PDw_Pz4- on /tools/base64 before you ship the snippet.

Try it yourself

Put what you've learned into practice with our free browser-native tool.

Open Tool →