Contact emails [email protected], [email protected]
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 (eg 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 (eg 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 (eg links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (eg, 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. -- 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 [email protected]. To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/6acf54ea.6e0b2b3a.151e33.12ef.GAE%40google.com.
