JavaScript Document characterSet Property

What You’ll Learn

Document.characterSet is a read-only instance property that returns the character encoding label the browser uses to render the page (such as UTF-8). Learn MDN’s encoding-vs-set distinction, the charset alias, how meta tags affect encoding, and five examples with try-it labs.

Introduction

When a browser loads an HTML file, it must decide how to turn bytes into characters. That decision is the document’s character encoding. Modern pages almost always use UTF-8, which supports emoji, accented letters, and scripts from many languages.

document.characterSet lets JavaScript read which encoding label the browser applied—useful for debugging mojibake (garbled text), verifying your <meta charset> tag, or logging locale diagnostics in support tools.

Related Document tutorials: body, Document constructor, textContent.

Understanding Document.characterSet

A read-only instance property on Document. Its value is a string naming the encoding the document is currently rendered with.

• Value — encoding label string (e.g. UTF-8, ISO-8859-1).
• Read-only — you cannot change encoding by assigning to this property.
• Alias — document.charset returns the same value (legacy name).
• Typical modern value — UTF-8 when <meta charset="utf-8"> is set.
• Related — document.inputEncoding reflects the encoding used to decode the document (often matches).

📝 Syntax

document.characterSet

Value

A string — the document’s character encoding label.

MDN example

console.log(document.characterSet);
// e.g. "UTF-8" or "ISO-8859-1"

⚖️ Encoding-related Document properties

Examples Gallery

Examples follow MDN Document: characterSet. Use View Output or Try It Yourself for each case.

console.log(document.characterSet);
// "UTF-8" on most modern pages

UTF-8

const isUtf8 =
  document.characterSet.toUpperCase().replace(/_/g, "-") === "UTF-8";

console.log("Using UTF-8:", isUtf8);
console.log("Actual encoding:", document.characterSet);

Using UTF-8: true
Actual encoding: UTF-8

console.log(document.characterSet);
console.log(document.charset);
console.log(document.characterSet === document.charset); // true

UTF-8
UTF-8
true

const meta = document.querySelector('meta[charset]');
const declared = meta ? meta.getAttribute("charset") : "(none)";

console.log("meta charset:", declared);
console.log("document.characterSet:", document.characterSet);

meta charset: utf-8
document.characterSet: UTF-8

const encodingInfo = {
  characterSet: document.characterSet,
  charset: document.charset,
  inputEncoding: document.inputEncoding,
  lang: document.documentElement.lang || "(not set)"
};

console.log(JSON.stringify(encodingInfo, null, 2));

{
  "characterSet": "UTF-8",
  "charset": "UTF-8",
  "inputEncoding": "UTF-8",
  "lang": "en"
}

🚀 Common Use Cases

• Debugging mojibake — confirm the browser decoded the page as UTF-8.
• Support tooling — log encoding in bug-report bundles.
• Legacy site audits — detect ISO-8859-1 pages that need migration.
• CMS diagnostics — verify meta charset survived template rendering.
• Not for changing encoding — fix HTML/HTTP instead of JavaScript.
• i18n education — teach bytes, encoding labels, and Unicode.

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• Read-only — change encoding via meta tag or HTTP headers, not this property.
• Despite the name, returns the encoding label (MDN note).
• document.charset is a legacy alias with the same value.
• Always use <meta charset="utf-8"> in new HTML documents.
• Related: body, textContent, Document constructor.

💡 Best Practices