{"id":8896,"date":"2026-03-11T17:24:06","date_gmt":"2026-03-11T22:24:06","guid":{"rendered":"https:\/\/frontendmasters.com\/blog\/?p=8896"},"modified":"2026-04-02T16:28:28","modified_gmt":"2026-04-02T21:28:28","slug":"form-associated-custom-elements-in-practice","status":"publish","type":"post","link":"https:\/\/frontendmasters.com\/blog\/form-associated-custom-elements-in-practice\/","title":{"rendered":"Form-Associated Custom Elements in Practice"},"content":{"rendered":"\n

I was well over three-quarters of the way through rewriting the AgnosticUI components in Lit<\/a> when I realized I had a massive blind spot. My <ag-input><\/code> looked solid and fired events correctly, but it lacked Form-Associated Custom Element<\/a> (FACE) support. This meant it was essentially invisible to native <form><\/code> submissions.<\/p>\n\n\n\n

I was completely unaware of this until a conversation with my friend Marc van Neerven<\/a>. We were discussing the nuances of Web Components and Shadow DOM<\/a> when Marc pointed out the importance of form association<\/strong>.<\/p>\n\n\n\n

Fueled by the mild embarrassment of having missed something so fundamental, I immediately started digging through articles like ElementInternals and Form-Associated Custom Elements<\/a> to understand how this Form-Associated Custom Element<\/em> stuff worked. Of course, I understood that native HTML form controls have built-in submission logic and FormData<\/code> support, but I had absolutely no idea a FACE API even existed.<\/p>\n\n\n\n

It’s a massive facepalm moment when you believe you’re “code complete” on a dozen different form components, only to realize they don’t support the most basic functionality of a form. If you wrap a naively built custom element in a <form><\/code> and hit submit, the browser will have no idea the component is even there. Try setting a breakpoint on your submit handler; you’ll see an empty FormData<\/code> object staring back at you.<\/p>\n\n\n\n

\"Comparison<\/figure>\n\n\n\n

That empty object is what eventually reaches your server. Additionally, if you call form.reset()<\/code>, your custom fields remain filled, and even a <fieldset disabled><\/code> wrapper gets completely ignored.<\/p>\n\n\n\n

Fixing this meant retrofitting every single form component in AgnosticUI. It was a massive undertaking, but it forced me to distill the spec’s complexities into a single, reusable Lit mixin. This helped encapsulate the boilerplate in one place, keeping the code DRY and ensuring my components finally became form-aware.<\/p>\n\n\n\n

The following is what I learned during that process.<\/p>\n\n\n

\n
\n

Article Series<\/h3>\n <\/header>\n
\n
    \n
  1. \n Post Mortem: Rewriting AgnosticUI with Lit Web Components<\/a>\n <\/li>\n
  2. \n Form-Associated Custom Elements in Practice<\/a>\n <\/li>\n
  3. \n Shadow DOM Focus Delegation: Getting\u00a0delegatesFocus\u00a0Right<\/a>\n <\/li>\n <\/ol>\n <\/div>\n<\/div>\n\n\n\n

    What FACE Actually Is<\/h2>\n\n\n\n

    Enabling FACE starts with a deceptive bit of boilerplate. You tell the browser your element wants to participate in forms, and then you grab a handle to the ElementInternals API<\/a>.<\/p>\n\n\n

    class<\/span> MyInput<\/span> extends<\/span> HTMLElement<\/span> <\/span>{\n  static<\/span> formAssociated = true<\/span>; \/\/ The \"I'm a form control\" flag<\/span>\n\n  constructor<\/span>() {\n    super<\/span>();\n    \/\/ This gives you the keys to the kingdom<\/span>\n    this<\/span>._internals = this<\/span>.attachInternals();\n  }\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    \"Diagram<\/figure>\n\n\n\n
    If only it ended there. While those two steps “engage” the API, the actual work happens through ElementInternals<\/code>. This is your side of the contract with the browser’s form system. It isn’t just a single property; it’s a suite of methods and properties that let your component finally talk to the parent <form><\/code>.<\/p>\n\n\n\n
    Through _internals<\/code>, you can:<\/p>\n\n\n\n