This repository was archived by the owner on Jul 21, 2026. It is now read-only.
Repository navigation
This repository was archived by the owner on Jul 21, 2026. It is now read-only.
[RRFC] FormAssociated mixins #43
Description
- I searched for an existing RRFC which might be relevant to my RRFC
Motivation
Building a form associated custom element requires a lot of common boilerplate:
- Setting
static formAssociated = true - Attaching ElementInternals
- Setting a default ARIA role
- Calling
internals.setFormValue()when needed - Representing the element's form value and the element state
- Exposing the value to the element's public API
- Handling
formDisabledCallback() - Handling
formResetCallback()andformStateRestoreCallback()
Example
A simple-ish FormAssociated() element, with validation, might just forward an input's value to the element's value:
import {FormAssociated, value} from '@lit-labs/form';
class MyFormElement extends FormAssociated(LitElement, {
role: 'textbox'
}) {
@formValue()
accessor value: string = '';
@query()
accessor #input: HTMLInputElement;
render() {
return html`<input .value=${this.value}> @input=${this.#onInput}`;
}
#onInput(e) {
this.value = e.target.value;
}
protected _checkValidity() {
if (this.value.length < 5) {
return {
flags: { tooLong: true },
message: "value is too long",
anchor: this.#input,
};
}
}
}In this case the FormAssociated mixin would:
- set
static formAssociated = true - set
internals.role - call
setFormValue()whenvaluechanges - Implements
formStateRestoreCallback()to reset the value.
How
A FormAssociated() mixin, paired with @internals, @formValue and @formState decorators.
Current Behavior
Desired Behavior
References
- n/a
Reacted by Casey Watts, Angelique, Konnor Rogers, Jeroen Zwartepoorte, Leonard Greulich, Anand Kumar, Stefanos Lignos, Julian Cataldo, Marco Muser and Erik Harper
Activity
justinfagnani commentedon Sep 21, 2024
There are a lot of possible variations on what a mixin might provide, especially in terms of the public API it creates on the element.
I think the the minimal end of the spectrum, like the sketch above, a mixin might add no new public API. It just helps the element author coordinate the form value, form associated callbacks, and form methods on ElementInternals.
Another point on the spectrum is to emulate many of the the methods of HTMLInputElement, like
checkValidity(),validity, etc. HTMLInputElement is also very customizable in terms of validity constraints. I don't think most elements will want the element users to customize the constraints, but the element author may want to use a similar declarative API (min,max,pattern, etc) to define constraints, rather than have just a validity checking callback.So we may want to start with a minimal-API-adding mixin, then layer a richer API mixin on top of that. The minimal-API mixin can optionally have support for pluggable constraints.
maxpatiiuk commentedon Sep 21, 2024
If that is the case, could FormAssociated be developed as a controller instead?
That would provide more flexibility and (marginally?) better performance.
justinfagnani commentedon Sep 21, 2024
No, because it needs to override the form associated instance methods like
formResetCallback().jpzwarte commentedon Sep 21, 2024
I love this. One thing though that should be considered & documented carefully is how to make such a custom form control accessible.
I'm not sure browsers are fully there yet for formAssociated controls.
JamesIves commentedon Sep 29, 2024
Supportive of this. Working with forms is fairly confusing, so utilities like this are really helpful.
caseywatts commentedon Mar 18, 2026
Here's a recent blog post that covers formAssociated pretty thoroughly!
https://frontendmasters.com/blog/form-associated-custom-elements-in-practice/