Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 39 ยท Forms and Accessibility

Validation with ElementInternals

Add native-style constraint validation to custom form controls with setValidity, ValidityState flags, validation messages and :invalid or :user-invalid styling.

Native inputs validate themselves: required, min, pattern and type="email" stop a bad submission and show a message. A form-associated custom element can join the same system. Once you do, form.checkValidity(), form.reportValidity(), the browser's validation bubble and the :invalid pseudo-class all work with your component, with no custom plumbing.

The key method is internals.setValidity(flags, message, anchor).

setValidity basics

  • flags is an object of ValidityState flags set to true: valueMissing, typeMismatch, patternMismatch, tooLong, tooShort, rangeUnderflow, rangeOverflow, stepMismatch, badInput and customError.
  • message is the text shown to the user. It is required when any flag is set.
  • anchor is an optional element inside the control that the browser bubble should point at (and focus).
  • Calling setValidity({}) with an empty object marks the control valid and clears the message.

Call it whenever the value changes, and again when attributes like required change.

A required tag input

The outline colors come from CSS: x-pin:invalid and x-pin:valid work on the custom element because it is form-associated and has real validity state. You did not have to write any class toggling.

With novalidate on the form, as above, the browser does not block submission, so your handler decides what to do. Remove novalidate and the browser itself will block the submit event and show its bubble next to your inner input.

Reading validity from outside

All the usual APIs work because ElementInternals exposes them, and the host forwards them if you add simple getters:

JavaScript
get validity() { return this.#internals.validity; }
get validationMessage() { return this.#internals.validationMessage; }
get willValidate() { return this.#internals.willValidate; }
checkValidity() { return this.#internals.checkValidity(); }
reportValidity() { return this.#internals.reportValidity(); }

In the demo above you called form.checkValidity() and read validationMessage from form.elements.pin. Forwarding these members is what makes your component feel native to script authors.

Choosing messages and flags

Pick the flag that best describes the problem, even though only the message is shown. Scripts and CSS can inspect validity.valueMissing, and assistive tools may use the flag category. Use customError for rules that have no native equivalent, such as "end date must follow start date".

Messages should say what to do, in plain language: "Enter a date after the start date" beats "Invalid".

Validating on change vs on submit

Run setValidity on every input so :invalid is always accurate. But showing red outlines before a person has had a chance to type is unfriendly. Two modern tools help:

  • The :user-invalid and :user-valid pseudo-classes match only after the user has interacted with the control. Prefer them for visible error styling in browsers that support them.
  • Or track a touched flag yourself and only show errors once it is set.
Delay the error until the user has interacted

Click into the field and leave it empty, then click away: the message appears only after the blur. Typing a name clears it. The aria-live region announces the message to screen readers, which connects this topic to the ARIA lesson.

Common mistakes

  • Forgetting to call setValidity({}) to clear an earlier error, leaving the control invalid forever.
  • Passing a flag without a message (the call throws).
  • Passing an anchor that is not inside the element's own tree.
  • Validating only on submit, so :invalid and checkValidity() are stale.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you mark a custom control valid again?

    An empty flags object clears every flag and the validation message.
  2. 2. What is required when you set a flag in setValidity?

    setValidity throws if a flag is true and no message is given.
  3. 3. Which CSS selector reacts to a custom form control's validity?

    Form-associated custom elements take part in :valid and :invalid like native controls.
  4. 4. Why prefer :user-invalid over :invalid for error styling?

    :user-invalid waits until the user has interacted, avoiding red fields on a blank form.

Summary

  • setValidity(flags, message, anchor) plugs a custom control into constraint validation.
  • Call it on every value or attribute change, and clear it with an empty object.
  • :valid, :invalid, form.checkValidity() and the browser bubble then just work.
  • Delay visible errors until interaction, using :user-invalid or your own touched flag.

Next: ARIA and ElementInternals