Ready for Developer Testing: 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

We are proposing a Spell Check Custom Dictionary API: a per‑document based, transient dictionary that supplements the browser's built-in spell-checking dictionaries. It does not change how those built-in dictionaries behave. The API lets a web page add words to and remove words from the Spell Check Custom dictionary. During spell checking, the browser's spell checker also checks words against this dictionary, so matching words are not flagged for spelling errors. This gives pages a way to programmatically suppress spell-check false positives within their own document, without requiring any action from users.

Blink component

Blink>Editing>Spellcheck

Web Feature ID

Missing feature

Search tags

Spell Check Custom Dictionary API

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: Under consideration (https://github.com/mozilla/standards-positions/issues/1384) Discussions are in progress

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/646) Discussions are in progress

Web developers: No signals

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?

No information provided

Debuggability

Because the API is intentionally write-only/unobservable, there is no DevTools surface for inspecting the dictionary. Authors debug by observing whether words are flagged in editable regions.

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

No
Yes on desktop; partial/conditional on Android and Android WebView. The API surface (document.spellCheckCustomDictionary, SecureContext) is implemented in Blink and is platform-independent. Custom words are applied as a renderer-side suppression filter over spell-check results (SpellCheck::CreateTextCheckingResults), so the behaviour is independent of the spell-check backend: - Windows — hybrid native + Hunspell. Custom words are filtered before the hybrid Hunspell re-check. Supported. - macOS — native (NSSpellChecker) via the browser. Supported. - Linux / ChromeOS — Hunspell in the renderer (same code path). Supported. - Android — native Android spell checker via SpellCheckerSessionBridge. Misspellings reported through the browser's spell-check result path are suppressed. However, misspelling indications that originate from the Android IME/keyboard during composition (rendered as suggestion markers, not through the spell-check result callback) are outside the browser's spell-check pipeline and are not suppressed by this API. This is consistent with the feature being scoped to the browser's own spellchecker; a web page cannot override the system keyboard's dictionary. - Android WebView — same pipeline as Android and the filter applies, but spell checking is disabled by default in WebView (elements are only checked when they carry spellcheck="true"; see crbug.com/652314). The API therefore has no observable effect on WebView content that has not opted into spell checking. The Android IME caveat above applies here as well. The API is a no-op by design wherever spell checking is unavailable or disabled. On-device verification for Android and Android WebView is still pending.

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

No
The blocker is that the effect this API produces — a spelling squiggle appearing or disappearing — has no representation that a Web Platform Test can legitimately observe, Renderer unit tests and Manula WPT tests have been added to make up for this.

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

Requires code in //chrome?

False

Tracking bug

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

Estimated milestones

DevTrial on desktop

153

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/6185007701557248

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.