When we need customElements.whenDefined() to access methods

[mehrlander]

I have a question related to this thread, and the pattern I noticed in the examples for form controls:

  // Wait for controls to be defined before attaching form listeners
  await Promise.all([
    customElements.whenDefined('sl-button'),
    customElements.whenDefined('sl-checkbox'),
    customElements.whenDefined('sl-input'),
    customElements.whenDefined('sl-option'),
    customElements.whenDefined('sl-select'),
    customElements.whenDefined('sl-textarea')
  ]).then(() => {
    form.addEventListener('submit', event => {
      event.preventDefault();
      alert('All fields are valid!');
    });
  });

I'm trying to understand generally where this async handling is needed. It seems to be an issue with libraries that wrap the customElements.define() statement you would otherwise use to create a custom element. Is that right? Related article: 1. Related StackOverflow:2, 3.

In the form examples, it's interesting that the form itself is not a custom element, and the handler does not seem to use any properties or methods of the custom elements. I tried removing the await piece, keeping just the call to form.addEventListener., and it seemed still to work.

It seems like an important topic for libraries that wrap web components from my novice perspective. A related question then is whether one can easily capture all custom elements for a dynamic "when ready." This Stack Overflow answer points to a mechanism in Polymer that might help, but a quick search indicates that, despite shared origins, Lit may not support the same. Would it make sense for libraries that wrap web components to provide some mechanism to get them and/or wait for them?

I imagine there is much to unpack in this but I would value any insights or clarity you all could bring.

[claviska]

In the form examples, it's interesting that the form itself is not a custom element

This isn't always required, but if you attach your event listener too soon, it might interfere with Shoelace's ability to inject its own form control data when the formdata event is triggered. From the docs:

Shoelace uses event listeners to intercept the form’s formdata and submit events. This allows it to inject data and trigger validation as necessary. If you’re also attaching an event listener to the form, you must attach it after Shoelace form controls are connected to the DOM, otherwise your logic will run before Shoelace has a chance to inject form data and validate form controls.

That said, it's a good practice to make sure custom element form controls are indeed registered before accepting a form submission (and verify everything on the server, of course).

Aside from forms, you don't really need customElements.whenDefined() unless you're referencing a method or a property of the custom element right away. However, it never hurts to have it since the promise will resolve instantly when the element(s) are already defined.

[mehrlander]

Ah, that is interesting. So the listener here could be triggered, declaring all fields valid, unaware that other component-driven processes may not have completed that would have found otherwise.

Then there is also the distinction though between defining the custom element and inserting an instance into the DOM. I was looking a moment ago at the various life cycle callbacks relevant to custom elements. It raises the thought that really it's at the instance level that we'd need to make sure an element has been inserted into a form before we layer on event listeners. I'm imagining a form where the elements might not all immediately be inserted, but in truth I'm not familiar with the logic and assumptions of forms to begin with. I'll keep reading, but I appreciate the tip!

[blendtwenty]

I've been writing a dynamic form constructor this week where a form might have any number of shoelace elements (3 or 300..) its up to the user. I've found using a customElementsReady function handy.

Even for simple forms I would spend a bit of time debugging my form only to find I was waiting the definition of an input that isn't present in my form (ie, I listed 5 field types but my form only contained 4).

So now I do this:

no more listing each element type

// Target my form that contains some number of sl elements.
const form = this.shadowRoot.querySelector('form');

// Wait for those elements to be ready.
await customElementsReady(form);

// Do things knowing all custom-elements are ready.
this._attachFormSubmitListener();

customElementsReady function:

export async function customElementsReady (containerElement) {
  if (!(containerElement instanceof Element)) {
    throw new Error('The argument must be a DOM element.');
  }

  // Get all element names within the containerElement (ie, the <form>)
  const elementNames = Array.from(containerElement.querySelectorAll('*'))
    .map(el => el.localName)
    .filter((value, index, self) => self.indexOf(value) === index)
    .filter(name => name.includes('-'));

  // Create an array of promises for undefined custom elements
  const customElementsPromises = elementNames
    .map(name => customElements.whenDefined(name));

  // Wait for all custom elements to be defined
  await Promise.allSettled(customElementsPromises);
}

@claviska, wondering if a utility like this would suit Web Awesome.

[claviska]

It looks like this isn't documented yet but, if you're using the autoloader, you can import and await the discover function to do this.

import { discover } from '/cdn/shoelace-autoloader.js';

// ...

await discover(yourFormHere);

// All Shoelace components have been registered

I'm also thinking about dispatching an event on window to indicate when the initial discovery has completed.

[thomp361]

Some sort of loader is needed. @blendtwenty thank you, this code saved me lots of time!