Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 39 ยท Forms and Accessibility

Form-Associated Custom Elements

Build custom form controls that submit values, reset, and join a form like native inputs, using formAssociated, ElementInternals and setFormValue.

A custom <star-rating> is useless in a form if the value never reaches the server. Native controls take part in form submission automatically; a plain custom element does not. The platform's answer is the form-associated custom element: a custom element that opts in and gets a hidden connection to its form through ElementInternals.

After this lesson your components can be given a name, send a value when the form is submitted, show up in form.elements, and reset with the form.

Opting in

Two steps are needed:

  1. Declare static formAssociated = true on the class.
  2. Call this.attachInternals() in the constructor and keep the result.

Then use internals.setFormValue(value) whenever the control's value changes. The value is what FormData and the submission will contain, under the element's name attribute.

A rating control that submits a value

The submit handler prints the form data instead of posting it. You will see stars in the result with the number you picked. Press Reset and the stars clear, because the form calls your formResetCallback.

Without setFormValue, the element would be form-associated but contribute nothing. Passing null removes the entry from the submission, which is how you say "no value".

What you get from ElementInternals

attachInternals() returns an object with form-related and accessibility-related powers. The form ones:

Member Purpose
setFormValue(value, state?) Value to submit (string, File or FormData)
form The owning <form>, or null
labels The <label> elements pointing at the control
setValidity(flags, message, anchor?) Mark invalid with a message (next lesson)
willValidate, validity, validationMessage, checkValidity() Constraint validation state
states Custom pseudo-class states such as :state(checked)

You also gain the name, form and type behaviours: reading element.form through your own getter, and being listed in form.elements.

Lifecycle callbacks for forms

Form-associated elements get four extra callbacks:

  • formAssociatedCallback(form): the element was attached to or removed from a form (form may be null).
  • formDisabledCallback(disabled): a surrounding <fieldset disabled> or the disabled attribute changed.
  • formResetCallback(): the form was reset; restore the default value.
  • formStateRestoreCallback(state, mode): the browser restores saved state (back button, autofill).
Watching the form callbacks

Disabling the fieldset calls formDisabledCallback(true) automatically. Respect it: a disabled control should ignore input and should not submit a value (the browser leaves it out of submission itself).

Setting the value state

setFormValue(value, state) takes an optional second argument. The first is the submission value; the second is the restoration state, which can be richer (for example the raw text typed in a masked input, while the submission value is the formatted result). The browser hands it back in formStateRestoreCallback.

Choosing the right approach

If your component is just a styled wrapper, wrapping a real <input> inside the light DOM is often simplest, because the native input is already associated. Form-associated custom elements shine when the control has no native equivalent (rating, tag input, date range, signature pad) or when the value is not text.

A shadow DOM that contains an <input> does not take part in the outer form, which is exactly why this API exists.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must a class declare to be form-associated?

    The static formAssociated flag, together with attachInternals(), opts the element in.
  2. 2. How does a custom control give its value to FormData?

    setFormValue is the channel to the form; the value is submitted under the element's name attribute.
  3. 3. When is formResetCallback called?

    The form's reset action calls it so the control can restore its default.
  4. 4. What does passing null to setFormValue do?

    null means there is no value, so the control contributes nothing to the form data.

Summary

  • Opt in with static formAssociated = true and attachInternals().
  • setFormValue sends the value; the element's name is the key.
  • Implement formResetCallback and formDisabledCallback for native-like behavior.
  • Use this for controls without a native equivalent; wrap a native input when one exists.

Next: Validation with ElementInternals