Intent to Ship: Spell check custom dictionary API

[Chromestatus]

Contact emails

zs...@igalia.com, sche...@chromium.org

Explainer

https://github.com/Igalia/explainers/tree/main/spell-check-dictionary

Specification

https://github.com/whatwg/html/pull/12590

Design docs

https://github.com/Igalia/explainers/tree/main/spell-check-dictionary
https://docs.google.com/document/d/1ND1a1Z4i6kXMHqMwEyRkHSj5VVTWgX5Ya0aNLgVQYGw/edit?tab=t.0#heading=h.kmfizh6cwyy4

Summary

Adds document.spellCheckCustomDictionary, which lets a page add words to and remove words from a per-document dictionary that the browser's spell checker consults alongside its built-in dictionaries. Matching words are no longer flagged as misspelled in that document, so sites with domain-specific vocabulary, such as product names, technical terms or proper nouns, can suppress false positives without asking users to edit their browser dictionary. The words last only for the document's lifetime and cannot be read back.

Blink component

Blink>Editing>Spellcheck

Web Feature ID

spell-check-custom-dictionary

Motivation

Spell checkers routinely flag words that are correct within a particular site but unknown to general dictionaries. Examples include: - A Pokémon wiki containing names like Pikachu or Charmander. - A financial analysis dashboard referencing company‑specific product names or tickers. - A medical or scientific tool using specialized terminology. False positives in these contexts are distracting, misleading, and erode user trust. While browsers allow users to add custom words via browser settings panel, there is currently no way for pages to provide a custom dictionary programmatically that applies only within their own context in order to reduce those false positives. Authors need a way to treat domain‑specific words as “known” without requiring user intervention.

Initial public proposal

https://github.com/Igalia/explainers/tree/main/spell-check-dictionary

Search tags

spellcheck, spelling, custom dictionary, spellCheckCustomDictionary, addWords, removeWords

TAG review

https://github.com/w3ctag/design-reviews/issues/1191

TAG review status

Issues addressed

Goals for experimentation

None

Risks

Interoperability and Compatibility

This feature is purely additive. It doesn't change existing spell-check behaviour, so the compatibility risk to existing content is minimal. Interoperability risk is low severity - the only difference the user sees is red squiggles under the custom words if the feature is absent.

Gecko: Neutral (https://github.com/mozilla/standards-positions/issues/1384) https://github.com/mozilla/standards-positions/issues/1384#issuecomment-5997330337

WebKit: Positive (https://github.com/WebKit/standards-positions/issues/646) https://github.com/WebKit/standards-positions/issues/646#issuecomment-6054915329

Web developers: Positive - Bloomberg requested this feature and sponsors Igalia's work on it. - Related demand elsewhere: * whatwg/dom#547: a developer with a canvas-based editor asks to add page-specific words to the browser spellchecker: https://github.com/whatwg/dom/issues/547#issuecomment-3969379684 * Electron added session.addWordToSpellCheckerDictionary() so apps can add custom words: https://www.electronjs.org/docs/latest/api/session#sesaddwordtospellcheckerdictionaryword

Other signals:

Ergonomics

The API is a minimal write-only pair (addWords/removeWords) taking string sequences, batched to match caller intent. It composes cleanly with existing spellcheck; no interaction with other high-usage APIs. Deliberately no read API, to keep the dictionary unobservable.

Activation

The API should be easy to adopt: one call and no setup is needed. It is not polyfillable.

Security

The API holds transient per-document state. There is no network exposure, and it neither reads nor modifies OS or browser dictionaries. It is per-frame based. the word set is owned by a single Document. Every frame gets its own independent set. The set is discarded when the document goes away. Input is validated with empty/whitespace-padded/ill-formed-UTF-16 words rejected and size-capped to prevent resource abuse. The API is write-only by design.

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

None expected. This feature is purely additive. It adds a new interface and a new Document attribute, doesn't change or deprecate any existing API, and doesn't change spell-check behaviour for pages that don't call it. Existing WebView apps are unaffected.

Debuggability

The API is write-only to page script by design: JavaScript can't read the dictionary back, so it can't be used to probe the user's spell-check state. Developers and tests can still see what a page has added: - DevTools UI : Application > Frames > [frame] > Frame details has a "Spell check custom dictionary" section listing the words that frame's document has added. - CDP : the experimental command Page.getSpellCheckCustomDictionary({frameId}) returns a frame's words in sorted order. The DevTools UI uses it, and automation tools can call it directly. It isn't available to page script. - Automated testing: the web test mock spellchecker supports the API, so tests can check that added words are no longer marked as misspelled. Following the DevTools console policy, the API logs no console messages.

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

No
Supported on Windows, macOS, Linux, ChromeOS, Android and Android WebView, with the known limitations on Android and WebView listed below. Not available on iOS. The API (document.spellCheckCustomDictionary, secure contexts only) and the word set are implemented entirely in Blink. Custom words are applied as a renderer-side filter over the spell-check results the renderer receives, so the same filter works with every spell-check backend: Hunspell on Linux and ChromeOS, NSSpellChecker on macOS, the Windows spell checker, and the Android platform spell checker. Any differences between platforms come only from what the underlying spell checker reports. Known limitations: - Android and Android WebView: misspellings surfaced by the IME/keyboard during composition are drawn as IME suggestion markers and never travel through the spell-check result path, so this API cannot suppress them. Misspellings reported through the browser's spell-check pipeline are suppressed correctly. - Android WebView: WebView disables spell checking by default (AwSettings), so there is nothing to check — and nothing to suppress — until the app or page opts in (e.g. spellcheck="true"). This is pre-existing WebView behaviour rather than a limitation of this API; with spell checking enabled, behaviour matches Android. - iOS: Chrome on iOS is built on WebKit and does not run Blink, so the API is not exposed. Windows, macOS, Linux and ChromeOS are fully supported.

Is this feature fully tested by web-platform-tests?

No
There are no WPTs yet. The tests for the API surface are currently in Chromium's wpt_internal, which is Chromium-only. We plan to upstream the API-surface tests to WPT alongside the spec PR. The API's only effect is whether a word gets a spelling marker. Spelling markers depend on the platform spellchecker and aren't observable from script, so there's no portable way for a WPT to assert them. Existing spellcheck features (e.g. the spellcheck attribute) have the same limitation. Chromium-side coverage of that effect: - Web tests that read spelling markers through the mock spellchecker. - Blink unit tests for input validation and word limits. - components/spellcheck for applying the filter to the hybrid, platform and spelling-service results, lifetime across navigation, and the UMA metric. - Manual tests in wpt_internal/spell-check-custom-dictionary/ for checking the squiggles visually on each platform, including WebView.

DevTrial instructions

https://github.com/Igalia/explainers/blob/main/spell-check-dictionary/DevTrial_instructions.md

Flag name on about://flags

No information provided

Finch feature name

SpellCheckCustomDictionaryAPI

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Tracking bug

https://issues.chromium.org/issues/428005649

Availability expectation

At launch the API will be available in Chromium-based browsers on Windows, macOS, Linux, ChromeOS, Android and Android WebView. It will not be available in Chrome on iOS, which uses WebKit. Mozilla's position is neutral (https://github.com/mozilla/standards-positions/issues/1384). WebKit engineers have reviewed the proposal and reported no major issues(https://github.com/WebKit/standards-positions/issues/646). Neither engine has announced implementation plans.

Adoption expectation

This is a feature requested by a client. we'd expect it will be used pretty soon once launched. Use scenarios include sites and editors with domain-specific vocabulary, such as wikis, technical documentation, CMS and rich-text editors, and medical or financial tools, to suppress false-positive misspelling marks. Because the feature isn't needed for things to work (without it, users just see extra squiggles), we expect sites to adopt it gradually through feature detection rather than all at once.

Adoption plan

- MDN documentation (https://issuetracker.google.com/issues/568348294) - The explainer, DevTrial instructions, and a demo page. - Tooling: DevTools shows a frame's custom words in Application > Frames > Frame details, and the experimental CDP command Page.getSpellCheckCustomDictionary makes them available to automated tests. - Continuing the WHATWG and standards-position discussions with Mozilla and WebKit to improve availability across browsers

Non-OSS dependencies

Does the feature depend on any code or APIs outside the Chromium open source repository and its open-source dependencies to function?

No. The word set and the suppression filter are entirely in Blink/Chromium.

Estimated milestones

Shipping on desktop	159
DevTrial on desktop	153
Shipping on Android	159
Shipping on WebView	159

Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

The spec PR (https://github.com/whatwg/html/pull/12590) is under review at WHATWG and the proposal is at Stage 2 (https://github.com/whatwg/html/issues/12388). We don't expect changes to the name or shape of the shipped API. The open feedback comes from the W3C i18n WG review (https://github.com/w3c/i18n-actions/issues/222). It raises two areas including language metadata and matching rules that may lead to later, backward-compatible changes. In both cases the compatibility risk is low: changes would be additive or would only reduce false-positive spelling marks.

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/6185007701557248?gate=4929988981424128

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/687a1d04.170a0220.2dad83.0168.GAE%40google.com

This intent message was generated by Chrome Platform Status.

[Philip Jägenstedt]

Hi,

I see that https://github.com/whatwg/html/pull/12590 is a draft with seemingly no review of the actual spec text. If https://github.com/WebKit/standards-positions/issues/646 is going to be resolved as positive (it's not yet) then maybe you can entice a WebKit contributor to carefully review the spec?

In other words, I'd like to see some more effort to progress the spec here.

Best regards,

Philip

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/6acf54ea.6e0b2b3a.151e33.12ef.GAE%40google.com.

[Ziran Sun]

Thanks for the comment! We will look at this.

[Alex Russell]

Any updates here? This feature looks great and I'd *like* to give it a go-ahead if we think the spec is in better shape.

[Brian Kardell]

Hey sorry, we've been out on hoildays last week, I am out at TPAC this week and next week at other meetings. I pushed a few changes to the PR before I left, but I need to come back to it when (I imagine many of us) are less swamped with TPAC.  Happy to hear any HTML spec feedback if you've got any in the meantime.