v153 · spell check dictionary

One document, one dictionary

Per-document, transient, write-only. Three words in the specification that decide how an application has to be built around this API — and all three are observable here, because a document is a thing you can count, replace, and watch disappear.

Three documents, side by side

This page and two same-origin frames. Every one has its own document, so every one would have its own dictionary — adding a word here would do nothing for the field in either frame.

this page

The document you are reading.

frame A

frame B

Reading the three documents…

The identity row is the interesting one: it is a token this page assigns to each document object the first time it sees it. Navigate frame A and the token changes, because the object did — and with it, everything hanging off it.

What each word costs you

The three constraints, and the code they force
constraintwhat it meanswhat your application has to do

The shape that follows

// Your own record is the source of truth. The browser will not tell you
// what is in its dictionary, and the dictionary will not survive a
// navigation, so both facts point at the same design.
const glossary = new Set();

function useGlossary(terms) {
  const added = terms.filter((term) => !glossary.has(term));
  if (added.length === 0) return;
  document.spellCheckCustomDictionary?.addWords(added);
  for (const term of added) glossary.add(term);
}

// After a soft navigation inside a single-page application the document is
// the SAME one, so the dictionary survives — and your stale project terms
// are still exempt in the next project. Remove them deliberately.
function leaveProject(terms) {
  document.spellCheckCustomDictionary?.removeWords(terms);
  for (const term of terms) glossary.delete(term);
}

The single-page case is the trap. "Transient" means the dictionary dies with the document, and in an application that never replaces its document, that is never — so a glossary added on one screen is still in effect three screens later unless something takes it out.

see also