Before Shadow DOM, you needed a framework to encapsulate component templates or styling. Shadow DOM was a game-changer because it allows you to code UI components without their logic clashing with other components using just the web platform. Shadow DOM poses challenges when HTML elements encapsulated by Shadow DOM need to participate in a form.

In this post, I'll provide an overview of form-associated custom elements. Form-associated custom elements is a web specification that allows engineers to code custom form controls that report value and validity to 

, while also promoting a fully accessible user experience.

Form-associated custom elements are just one of the many topics covered in my book 

Fullstack Web Components: Complete Guide to Building UI Libraries with Web Components

. It features step-by-step walkthroughs and explanations about coding a UI Library of Web Components in Storybook and building an application using custom elements.

With the encapsulation provided by Shadow DOM, engineers can code UI components where the CSS styling doesn't collide with other components. Shadow DOM provides a DOM tree for an element separated from the rest of the Document Object Model (DOM). The separation of concerns promoted by Shadow DOM is a boon for coding reusable UI components.

While Shadow DOM has several benefits, there are some complications when elements embedded in Shadow DOM have to interact with 

. Suppose you wanted to code a custom checkbox component using Shadow DOM. Checkboxes usually require a significant amount of CSS styling that overrides the browser defaults to match a given mockup. You code an autonomous custom element and style the 

 in the context of Shadow DOM so the styling doesn't conflict with other elements. You give the component a tag name of 

. Just when you think you're following best practices, you place an instance of the custom element as a child of 

Upon inspection in Dev Tools, you may notice the 

 cannot participate with the form. You can inspect this phenomenon in this 

 by design can report value and validity back to 

When coding reusable components it's a good idea to provide an interface for web engineers that's familiar. It's typical for 

 to have access to the parent form directly on the element. You can inspect this behavior in the following 

 is found in an entirely different DOM tree (Shadow DOM), the 

 embedded in Shadow DOM can't participate in the form.

In 2019, a new specification was proposed that solves this issue. Form-associated custom elements allow web engineers to use the benefits of Shadow DOM while providing an API that enables custom elements to participate in 

. Form-associated custom elements have all the benefits of autonomous custom elements. They can implement Shadow DOM and use the typical custom lifecycle hooks because they inherit from 

If you've coded autonomous custom elements, learning how to code form-associated custom elements is fairly similar. In the following examples, I'll demonstrate how a checkbox embedded in Shadow DOM can participate in an HTML form by implementing 

Before I mentioned that form controls that are native to the browser like 

. The form control is added to an Array-like interface on 

, allowing web engineers to loop through the form controls to handle common tasks like validation.

 the same way, you simply need to set the value of a static property named 

. the below example written with TypeScript does just that.

export class Checkbox extends HTMLElement {
  static formAssociated = true;
  constructor() {
    ....

 behaves when it's a direct descendant of 

 can be called with provides the same interface, along with the Accessibility Object Model (AOM). By setting a property on 

export class Checkbox extends HTMLElement {
  _internals: ElementInternals;
  static formAssociated = true;
  constructor() {
    super();
    this._internals = this.attachInternals();

Later in this post, I'll provide an example of how you can reference a method on the 

 interface that aids with validation. Before that, we should resolve some discrepancies between 

. If we expect engineers to reuse this component, it should behave similarly to 

, which has a well-known interface. To provide parity between 

, let's define some getters and setters on 

. First, make a getter that returns a reference of the 

 so you can easily reference the element with 

  get checkbox(): HTMLInputElement {
    return this.shadowRoot?.querySelector("input") as HTMLInputElement;
  }

Next, define a getter and setter for the state of the checkbox. It's probably a good idea to make the 

 the single source of truth here. Any getter and setter defined on 

 either returns the value or sets the value of 

  get checked(): boolean {
    return this.checkbox.checked;
  }
  set checked(state: boolean) {
    this.checkbox.checked = true;
  }

We could introduce several more properties on 

 to provide parity between it and a typical 

While coding a UI library filled with form-associated custom elements, I found a couple of challenges in making the components reusable. Suppose you wanted to add validation logic to 

, including all the logic there. In the below example, I call 

 interface, which reports the validity of the input to 

. This is convenient, however placing this logic here doesn't give a web engineer the ability to configure validations per business logic in different scenarios.

  onValidate(state: boolean) {
    if (!state) {
      this._internals.setValidity({ customError: true }, "required");
    } else if (state === true) {
      this._internals.setValidity({});
    }
  }

A higher-level validation pattern is required that would allow engineers to loop through form controls and validate an entire form.

Another challenge had to do with making inline validation messages accessible. Getting screen readers to interpret validation messages as errors that should be read aloud at first seems tricky because of Shadow DOM, although is possible using WAI-ARIA attributes. Suppose this were the template instead of just the input. If the form control is invalid, custom logic could populate the 

 with relevant content. The WAI-ARIA attributes provide an immediate response for screen readers.

Did you like what you read here? In the book 

, you'll code a form-associated custom element, bringing all the features necessary to reuse that component in an enterprise-grade web application. You'll not just learn how to provide parity between the form control well-known elements like 

, but also discover a pattern for implementing reusable validations that validate an entire form. You'll also tackle challenges with making form-associated custom elements accessible. This is just in Chapter 3! 

 provides everything you need to know to code an entire UI library of custom elements.

Are you looking to code Web Components now, but don't know where to get started? I wrote a book titled 

Fullstack Web Components:Complete Guide to Building UI Libraries with Web Components

, a hands-on guide to coding UI libraries and web applications with custom elements. In 

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder"> Form-associated custom elements FTW!</h1><p>Before Shadow DOM, you needed a framework to encapsulate component templates or styling. Shadow DOM was a game-changer because it allows you to code UI components without their logic clashing with other components using just the web platform. Shadow DOM poses challenges when HTML elements encapsulated by Shadow DOM need to participate in a form.</p><p>In this post, I'll provide an overview of form-associated custom elements. Form-associated custom elements is a web specification that allows engineers to code custom form controls that report value and validity to <code>HTMLFormElement</code>, while also promoting a fully accessible user experience.</p><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>Form-associated custom elements are just one of the many topics covered in my book <em><a href="https://www.newline.co/courses/fullstack-web-components" target="_blank" rel="noopener noreferrer nofollow">Fullstack Web Components: Complete Guide to Building UI Libraries with Web Components</a></em>. It features step-by-step walkthroughs and explanations about coding a UI Library of Web Components in Storybook and building an application using custom elements.</p></div></div><h2 class="heading-anchor-text" id="the-problem"><span>The Problem</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#the-problem">#</a></h2><p>With the encapsulation provided by Shadow DOM, engineers can code UI components where the CSS styling doesn't collide with other components. Shadow DOM provides a DOM tree for an element separated from the rest of the Document Object Model (DOM). The separation of concerns promoted by Shadow DOM is a boon for coding reusable UI components.</p><p>While Shadow DOM has several benefits, there are some complications when elements embedded in Shadow DOM have to interact with <code>HTMLFormElement</code>. Suppose you wanted to code a custom checkbox component using Shadow DOM. Checkboxes usually require a significant amount of CSS styling that overrides the browser defaults to match a given mockup. You code an autonomous custom element and style the <code>HTMLInputElement</code> with <code>type="checkbox"</code> in the context of Shadow DOM so the styling doesn't conflict with other elements. You give the component a tag name of <code>my-checkbox</code>. Just when you think you're following best practices, you place an instance of the custom element as a child of <code>HTMLFormElement</code>.</p><div style="min-height: 88px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/html" data-uniqueid="cm-sTEAdBLlGG4Vxh-XBF_qi" id="cm-sTEAdBLlGG4Vxh-XBF_qi">&lt;form&gt;
  &lt;my-checkbox&gt;&lt;/my-checkbox&gt;
&lt;/form&gt;</textarea></div><p>Upon inspection in Dev Tools, you may notice the <code>HTMLInputElement</code> cannot participate with the form. You can inspect this phenomenon in this <a href="https://codesandbox.io/embed/custom-element-and-form-brpp29?fontsize=14&amp;hidenavigation=1&amp;theme=dark" target="_blank" rel="noopener noreferrer nofollow">CodeSandbox</a>.</p><p><code>HTMLInputElement</code> by design can report value and validity back to <code>HTMLFormElement</code>, but only when <code>HTMLInputElement</code> is a direct descendent of <code>HTMLFormElement</code>.</p><div style="min-height: 88px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/html" data-uniqueid="cm-i6lLKH7G-SeoUhwuYxie3" id="cm-i6lLKH7G-SeoUhwuYxie3">&lt;form&gt;
  &lt;input type="checkbox" /&gt;
&lt;/form&gt;</textarea></div><p>When coding reusable components it's a good idea to provide an interface for web engineers that's familiar. It's typical for <code>HTMLInputElement</code> that are direct descendants of <code>HTMLFormElement</code> to have access to the parent form directly on the element. You can inspect this behavior in the following <a href="https://codesandbox.io/embed/htmlformelement-hdied1?fontsize=14&amp;hidenavigation=1&amp;theme=dark" target="_blank" rel="noopener noreferrer nofollow">CodeSandbox</a>.</p><p>Since the <code>HTMLInputElement</code> is found in an entirely different DOM tree (Shadow DOM), the <code>HTMLFormElement</code> doesn't recognize the <code>HTMLInputElement</code>.</p><figure class="photo figure-position-inline"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7sygxv8opy3711m7oml5.png" alt="my-checkbox contains a HTMLInputElement embedded in Shadow DOM" contenteditable="false"><div></div></figure><p>In short, <code>HTMLInputElement</code> embedded in Shadow DOM can't participate in the form.</p><h2 class="heading-anchor-text" id="enter-form-associated-custom-elements"><span>Enter Form-associated custom elements</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#enter-form-associated-custom-elements">#</a></h2><p>In 2019, a new specification was proposed that solves this issue. Form-associated custom elements allow web engineers to use the benefits of Shadow DOM while providing an API that enables custom elements to participate in <code>HTMLFormElement</code>. Form-associated custom elements have all the benefits of autonomous custom elements. They can implement Shadow DOM and use the typical custom lifecycle hooks because they inherit from <code>HTMLElement</code>.</p><p>If you've coded autonomous custom elements, learning how to code form-associated custom elements is fairly similar. In the following examples, I'll demonstrate how a checkbox embedded in Shadow DOM can participate in an HTML form by implementing <code>formAssociated</code> and <code>ElementInternals</code>.</p><p>Before I mentioned that form controls that are native to the browser like <code>HTMLInputElement</code> automatically participate in <code>HTMLFormElement</code>. The form control is added to an Array-like interface on <code>HTMLFormElement</code>, allowing web engineers to loop through the form controls to handle common tasks like validation.</p><p>For the <code>Checkbox</code> component to participate in <code>HTMLFormElement</code> the same way, you simply need to set the value of a static property named <code>formAssociated</code> to <code>true</code>. the below example written with TypeScript does just that.</p><p>If you wish to follow along, fork this <a href="https://codesandbox.io/embed/custom-element-and-form-brpp29?fontsize=14&amp;hidenavigation=1&amp;theme=dark" target="_blank" rel="noopener noreferrer nofollow">CodeSandbox</a> and start coding.</p><div style="min-height: 112px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/typescript" data-uniqueid="cm-9aMkC_Q_s2lYeKMyh_EKO" id="cm-9aMkC_Q_s2lYeKMyh_EKO">export class Checkbox extends HTMLElement {
  static formAssociated = true;
  constructor() {
    ....</textarea></div><p>Inversely, if you wish to reference <code>HTMLFormElement</code> on instances of <code>Checkbox</code>, similar to how <code>HTMLInputElement</code> behaves when it's a direct descendant of <code>HTMLFormElement</code>, a method inherited from <code>HTMLElement</code> called <code>attachInternals</code> can be called with provides the same interface, along with the Accessibility Object Model (AOM). By setting a property on <code>Checkbox</code> named <code>_internals</code> to what's returned by <code>attachInternals</code>, you effectively add the <code>ElementInternals</code> interface to <code>Checkbox</code>.</p><div style="min-height: 160px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/typescript" data-uniqueid="cm-znj3CbJSZ0Bkvpm1XfWEj" id="cm-znj3CbJSZ0Bkvpm1XfWEj">export class Checkbox extends HTMLElement {
  _internals: ElementInternals;
  static formAssociated = true;
  constructor() {
    super();
    this._internals = this.attachInternals();</textarea></div><h3 class="heading-anchor-text" id="parity"><span>Parity</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#parity">#</a></h3><p>Later in this post, I'll provide an example of how you can reference a method on the <code>ElementInternals</code> interface that aids with validation. Before that, we should resolve some discrepancies between <code>Checkbox</code> and a typical <code>HTMLInputElement</code>. If we expect engineers to reuse this component, it should behave similarly to <code>HTMLInputElement</code>, which has a well-known interface. To provide parity between <code>HTMLInputElement</code> and <code>Checkbox</code>, let's define some getters and setters on <code>Checkbox</code>. First, make a getter that returns a reference of the <code>HTMLInputElement</code> so you can easily reference the element with <code>this.checkbox</code> throughout the logic of the component.</p><div style="min-height: 88px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/typescript" data-uniqueid="cm-AivWEoHZ57VcJXPwyeUsX" id="cm-AivWEoHZ57VcJXPwyeUsX">  get checkbox(): HTMLInputElement {
    return this.shadowRoot?.querySelector("input") as HTMLInputElement;
  }</textarea></div><p>Next, define a getter and setter for the state of the checkbox. It's probably a good idea to make the <code>HTMLInputElement</code> the single source of truth here. Any getter and setter defined on <code>Checkbox</code> either returns the value or sets the value of <code>checked</code> on <code>this.checkbox</code>.</p><div style="min-height: 160px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/typescript" data-uniqueid="cm-4_tJ3K3v9M5DvV5xYM7Ds" id="cm-4_tJ3K3v9M5DvV5xYM7Ds">  get checked(): boolean {
    return this.checkbox.checked;
  }
  set checked(state: boolean) {
    this.checkbox.checked = true;
  }</textarea></div><p>We could introduce several more properties on <code>Checkbox</code> to provide parity between it and a typical <code>HTMLInputElement</code>, but we'll stop there for now.</p><h3 class="heading-anchor-text" id="lessons-learned"><span>Lessons Learned</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#lessons-learned">#</a></h3><p>While coding a UI library filled with form-associated custom elements, I found a couple of challenges in making the components reusable. Suppose you wanted to add validation logic to <code>Checkbox</code> and have the <code>class</code> another method called <code>onValidate</code>, including all the logic there. In the below example, I call <code>setValidity</code> on the <code>ElementInternals</code> interface, which reports the validity of the input to <code>HTMLFormElement</code>. This is convenient, however placing this logic here doesn't give a web engineer the ability to configure validations per business logic in different scenarios.</p><div style="min-height: 184px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/typescript" data-uniqueid="cm-EgVLH4-Ebhe_kqR8jFv7f" id="cm-EgVLH4-Ebhe_kqR8jFv7f">  onValidate(state: boolean) {
    if (!state) {
      this._internals.setValidity({ customError: true }, "required");
    } else if (state === true) {
      this._internals.setValidity({});
    }
  }</textarea></div><p>A higher-level validation pattern is required that would allow engineers to loop through form controls and validate an entire form.</p><p>Another challenge had to do with making inline validation messages accessible. Getting screen readers to interpret validation messages as errors that should be read aloud at first seems tricky because of Shadow DOM, although is possible using WAI-ARIA attributes. Suppose this were the template instead of just the input. If the form control is invalid, custom logic could populate the <code>&lt;div class="message"&gt;</code> with relevant content. The WAI-ARIA attributes provide an immediate response for screen readers.</p><div style="min-height: 112px"><textarea data-iscodemirror="true" class="d-none" data-mode="text/html" data-uniqueid="cm-2tNF5DeEGtfqHtaUbeNZk" id="cm-2tNF5DeEGtfqHtaUbeNZk">&lt;div class="control"&gt;
  &lt;input type="checkbox" aria-describedby="message" /&gt;
&lt;/div&gt;
&lt;div class="message" aria-role="alert" aria-live="assertive" id="message"&gt;&lt;/div&gt;</textarea></div><p>Did you like what you read here? In the book <em>Fullstack Web Components</em>, you'll code a form-associated custom element, bringing all the features necessary to reuse that component in an enterprise-grade web application. You'll not just learn how to provide parity between the form control well-known elements like <code>HTMLInputElement</code>, but also discover a pattern for implementing reusable validations that validate an entire form. You'll also tackle challenges with making form-associated custom elements accessible. This is just in Chapter 3! <em>Fullstack Web Components</em> provides everything you need to know to code an entire UI library of custom elements.</p><h2 class="heading-anchor-text" id="fullstack-web-components"><span>Fullstack Web Components</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#fullstack-web-components">#</a></h2><p>Are you looking to code Web Components now, but don't know where to get started? I wrote a book titled <em><a href="https://www.newline.co/courses/fullstack-web-components" target="_blank" rel="noopener noreferrer nofollow">Fullstack Web Components:Complete Guide to Building UI Libraries with Web Components</a></em>, a hands-on guide to coding UI libraries and web applications with custom elements. In <em><a href="https://www.newline.co/courses/fullstack-web-components" target="_blank" rel="noopener noreferrer nofollow">Fullstack Web Components</a></em>, you'll...</p><ul><li><p>Code several components using autonomous, customized built-in, and form-associated custom elements, Shadow DOM, HTML templates, CSS variables, and Declarative Shadow DOM</p></li><li><p>Develop a micro-library with TypeScript decorators that streamlines UI component development</p></li><li><p>Learn best practices for maintaining a UI library of Web Components with Storybook</p></li><li><p>Code an application using Web Components and TypeScript</p></li></ul><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20220621180336132_title_page-1200_FSWebComponents_r2.jpg" attachmentid="7303afb4-ad3f-4c05-9776-7bf7350ca9b5" contenteditable="false" data-width="1200" data-height="1591"><div></div></figure><p></p>

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Form-associated custom elements FTW!

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript