v153 · html · editing

document.spellCheckCustomDictionary

Every application with a text field has a vocabulary the browser has never heard of: product names, ticket prefixes, the internal acronym for the thing nobody can pronounce. The browser underlines all of it, every time, and the only escape has been to switch spell checking off entirely.

concepts

  1. The surface, probed

    Whether this browser has the attribute, what its two methods are, and why the recommended feature detection is the attribute rather than the interface — plus the secure-context requirement, tested rather than quoted.

  2. An editor with a project glossary

    A real editable field and a real term list. Add the glossary to the dictionary, or — here, today — watch the page tell you honestly that it cannot, and that it also cannot see what the browser decided.

  3. One document, one dictionary

    The API is per-document, transient and write-only. Two frames and a navigation make what that means observable: separate documents get separate dictionaries, and a new document starts empty.

why it shipped

A browser's spell checker has a dictionary and no way for a page to add to it. So an application that displays its own vocabulary — a bug tracker full of ticket ids, a design tool full of component names, a medical record full of drug names — shows the user a field of red underlines that mean nothing. The usual response is spellcheck="false" on the whole field, which throws away the checking that was working.

This adds a per-document exemption list. Words a page adds are treated as correctly spelled for that document, so the underlines that were noise disappear and the ones that were real typos stay.

the API

// Feature-detect on the attribute, not the interface: a browser without
// spell checking must not expose it at all.
if (document.spellCheckCustomDictionary) {
  document.spellCheckCustomDictionary.addWords([
    "Kubernetes", "PROJ-1841", "webtransport", "Kinlan",
  ]);
}

// And to take them back out again.
document.spellCheckCustomDictionary.removeWords(["PROJ-1841"]);

There is no way to read the list back. That is deliberate — an enumerable dictionary would be a fingerprinting surface and a record of what a user has been typing — and it means your application is responsible for its own bookkeeping.

enabling it now

Not available on the Chrome 150 used to build these pages, with or without a flag. Measured: "spellCheckCustomDictionary" in document is false both with and without --enable-experimental-web-platform-features, and no property matching /spell/i exists on Document.prototype.

Object.getOwnPropertyNames(Document.prototype).filter((n) => /spell/i.test(n))
// []

So the demos probe rather than demonstrate, and each one says what it would do the moment the attribute appears.

references