Enhanced Spell Checking on the Web

Here's some interesting stuff about browsers you might not know, and a new API proposal that might interest you...

You probably already know that if you have an editable area in a page with the spellcheck=true attribute set on it, then when a user clicks inside that area, it marks words as spelling errors, and you can style spelling errors with CSS. What you might not know is that feature is carefully designed and implemnted to avoid the huge fingerprinting risk of letting people know what's in your dictionary. A lot of the actual details are left to implementations and this means that not only will each OS/language highlight different spelling errors, but so will different browsers on the same machine, or even different profiles in the same browser!

But, if you think about websites and apps, they are highly likely to be accepting input related to something fairly specific, and highly unlikely to be in a common dictionary. Right? Online education is a great example where you'll find students writing words in different domains that are very common in that domain, but aren't in the common dictionary. Mathematics has its own words, so does chemistry, astronomy, and law. But schools are just one example. There are sites related to the stock market - lots of things there might look like gibberish otherwise. Or your hospital and doctor reports. The sites and apps for wine afficianados, or coffee lovers. There are sites where you submit fan fiction. There are forums where you discuss web development or cloud infrastructure. All of these will have common words that aren't in a general purpose dictionary.

That's a problem because it means we're marking lots of words as misspelled, but they aren't. Too many false positives and we easily overlook the ones that really are missspelled. In fact, in some cases it can even feel like more of an annoyance than a help.

So, there is a proposal currently in HTML for a new API called SpellCheck Custom Dictionary. For v1 the proposal is dead simple. It introduces a new document.spellCheckCustomDictionary with exactly two methods: .addWords(listOfWords) and .removeWords(listOfWords) - where listOfWords is an array of Strings. Those words are simply added to (or removed from) a Set internally which is consulted before consulting any other dictionaries (remember, there can be several) for the lifetime of that document. It doesn't affect other pages or the profile dictionary, or the browser dictionary or the OS dictionary, or any other things.

This is currently implemented by Igalia, with funding from Bloomberg Tech. It is currently available in Chrome Canary behind the experimental web platform features flag, and is scheduled to be shipping in on September 8, 2026 behind the same flag.

Because of its simplicity, it also works with JSON pretty nicely, you can just fetch a JSON array and call .addWords with the result. Of course, in practice you'll probably want to do this as a kind of progressive enhancement, not load the JSON immediately, and maybe handle and report various errors. For a whole lot of developers and use cases, it seems to me that a declarative API would be ideal. But we're not there yet. We have more to figure out with regard to how to express more than exact matches and so on. So, we'll get there... I hope.

In the meantime, however, I've made a tiny, but handy library which speculatively polyfills the basic outline of a declarative form in a safe way. With this, you just include the script and then you can add a <link> tag (or tags) pointing to JSON serializations of arrays of words, and adorn them with a data-spellcheck-dictionary marker-attribute.

<script src="dist/spellcheck-dictionary-loader.min.js"></script>
<link href="terms/domain-terms.json" data-spellcheck-dictionary>
<link href="terms/stocks.json" data-spellcheck-dictionary>

The script will wait until the initial parse is complete and then check for support. If the browser supports the custom dictionary API, it will load and add the words.

There is a /src and /dist version of this and it's very tiny (441 bytes over the wire with Brotli) and I expect it works for most common stuff.

It's "rough" though and not exactly how we'd probably expect a real implementation to work. For example, if you remove the link, it doesn't remove the words. If you change the href, it doesn't do anything, and so on. A real implementation would probably do those things. So, if you're interested in playing with something more complete, I've also included a -complete version of each: src/spellcheck-dictionary-loader-complete.js and dist/spellcheck-dictionary-loader-complete.min.js. The latter is still only 770 bytes over the wire with Brotli, but it's up to you how important that use is to you.

You can get all of the versions from this repo where there is also a start on several domain dictionaries to play with. What I think would be really great is to have some shared dictionaries that we work on together, so feel free to send PRs for additional words, this is really only a mostly generated starting list for demonstration purposes.

Please, let us know what you think - and thanks again to Bloomberg Tech for the funding!