More capable form controls

Many developers build custom form controls, either to provide controls that aren’t built in to the browser, or to customize the look and feel beyond what’s possible with the built-in form controls.

However, it can be difficult to replicate the features of built-in HTML form controls. Consider some of the features an &LTinput> element gets automatically when you add it to a form:

• The input is automatically added to the form’s list of controls.
• The input’s value is automatically submitted with the form.
• The input participates in form validation. You can style the input using the :valid and :invalid pseudoclasses.
• The input is notified when the form is reset, when the form is reloaded, or when the browser tries to autofill form entries.

Custom form controls typically have few of these features. Developers can work around some of the limitations in JavaScript, like adding a hidden &LTinput> to a form to participate in form submission. But other features just can’t be replicated in JavaScript alone.

Two new web features make it easier to build custom form controls, and remove the limitations of current custom controls:

• The formdata event lets an arbitrary JavaScript object participate in form submission, so you can add form data without using a hidden &LTinput>.
• The Form-associated custom elements API lets custom elements act more like built-in form controls.

These two features can be used to create new kinds of controls that work better.

Event-based API #

The formdata event is a low-level API that lets any JavaScript code participate in form submission. The mechanism works like this:

1. You add a formdata event listener to the form you want to interact with.
2. When a user clicks the submit button, the form fires a formdata event, which includes a FormData object that holds all of the data being submitted.
3. Each formdata listener gets a chance to add to or modify the data before the form is submitted.

Here’s an example of sending a single value in a formdata event listener:

const form = document.querySelector('form');
// FormData event is sent on &LTform> submission, before transmission.
// The event has a formData property
form.addEventListener('formdata', ({formData}) => {
// https://developer.mozilla.org/docs/Web/API/FormData
formData.append('my-input', myInputValue);
});

Try this out using our example on Glitch. Be sure to run it on Chrome 77 or later to see the API in action.

Browser compatibility #

Form-associated custom elements #

You can use the event-based API with any kind of component, but it only allows you to interact with the submission process.

Standardized form controls participate in many parts of the form lifecycle besides submission. Form-associated custom elements aim to bridge the gap between custom widgets and built-in controls. Form-associated custom elements match many of the features of standardized form elements:

• When you place a form-associated custom element inside a &LTform>, it’s automatically associated with the form, like a browser-provided control.
• The element can be labeled using a &LTlabel> element.
• The element can set a value that’s automatically submitted with the form.
• The element can set a flag indicating whether or not it has valid input. If one of the form controls has invalid input, the form can’t be submitted.
• The element can provide callbacks for various parts of the form lifecycle—such as when the form is disabled or reset to its default state.
• The element supports the standard CSS pseudoclasses for form controls, like :disabled and :invalid.

That’s a lot of features! This article won’t touch on all of them, but will describe the basics needed to integrate your custom element with a form.