Styling Native Spellcheck with CSS ::spelling-error

This article explains how the CSS ::spelling-error pseudo-element formats native spellchecker highlights in web applications. You will learn how browsers identify misspelled words, which CSS properties are supported to override default browser rendering, how to write the styling rules, and the technical limitations governing highlight pseudo-elements.

Understanding the ::spelling-error Pseudo-Element

The ::spelling-error pseudo-element is part of the CSS Pseudo-Elements Level 4 specification. It belongs to the family of highlight pseudo-elements, which also includes ::selection, ::target-text, and ::grammar-error.

Browsers typically format misspelled words inside editable regions—such as <textarea>, <input>, or elements with contenteditable="true"—with a native wavy red underline. The ::spelling-error pseudo-element allows authors to override this operating-system or browser-default visual indicator and apply custom styling to text segments that fail spellchecking.

Supported Properties

Because highlight pseudo-elements operate directly on the text rendering layer without altering the layout of the document, the CSS properties that can be applied to ::spelling-error are strictly limited. You cannot apply box-model properties like margin, padding, or display.

Only the following CSS properties are valid within ::spelling-error:

• Text Decoration: text-decoration-line, text-decoration-style, text-decoration-color, text-decoration-thickness
• Color: color
• Background: background-color
• Text Effects: text-shadow
• SVG Properties: fill, stroke, stroke-width

Customizing the Native Highlight

By default, a browser renders an error with a style equivalent to:

::spelling-error {
  text-decoration: wavy underline red;
}

To alter this visual indicator, target the pseudo-element globally or scope it to specific editable containers.

Example: Modifying Underline Appearance

You can change the color, thickness, or pattern of the underline to better match your application's design system:

/* Scoped to a specific editable container */
.editor::spelling-error {
  text-decoration-line: underline;
  text-decoration-style: dotted;
  text-decoration-color: #ff9800;
  text-decoration-thickness: 2px;
}

Example: Adding Background Highlighting

You can also apply background tinting or text color changes to make errors stand out clearly:

::spelling-error {
  color: #b71c1c;
  background-color: #ffebee;
  text-decoration: underline wavy #e53935;
}

Cascade and Inheritance Rules

Highlight pseudo-elements do not inherit styles down the standard DOM tree. Instead, they inherit from the corresponding highlight pseudo-element of their parent element. If no custom ::spelling-error rule is defined on a parent, the styling falls back to the user agent's default highlight styles, rather than inheriting custom text-decoration rules from standard CSS selectors.

Furthermore, if a user selects a piece of text that contains a spelling error, the styles defined in ::selection will paint over or combine with ::spelling-error depending on how the browser layers highlight elements. Typically, ::selection has a higher painting priority than ::spelling-error.

Implementation Requirements

For ::spelling-error styles to render, the target element must have native spellchecking enabled. Ensure the element is editable and that spellchecking is not disabled via HTML attributes:

<div contenteditable="true" spellcheck="true" class="editor">
  Thiss is an exampel of misspelled text.
</div>

If the browser does not recognize a word and the spellchecker activates, the native highlight is replaced immediately by the properties defined in your ::spelling-error declaration.