Enhance HTMLFormControlsCollection description

[estelle]

Added details about the elements included in the HTMLFormControlsCollection.

The elements IDL attribute must return an HTMLFormControlsCollection rooted at the form element's root, whose filter matches listed elements whose form owner is the form element, with the exception of input elements whose type attribute is in the Image Button state, which must, for historical reasons, be excluded from this particular collection.

related to #40760

[github-actions]

Preview URLs

• /en-US/docs/Web/API/HTMLFormControlsCollection

(comment last updated: 2025-09-10 08:25:44)

[Josh-Cena]

Personally I think this should be documented in elements (which we already do). HTMLFormControlsCollection is just a collection, and what's put inside this collection is up to each property that returns it, of which there happens to be only one, but this still feels out of place.

[estelle]

there are form controls that are not sent to the server that are included, so the list is an odd one, which is why i included it. It should be included on this page b/c of that, but perhaps in a different way. Do you have a suggestion?

For example,

1. fieldset is not sent to the server, but is in the collection.
2. If a control is nested in a form, but has a form attribute that dissociates it from its ancestor form, it is not included.
3. If a fieldset is not in the form, but has a form attribute that associates it, it is included, but not sent. It's descendant form controls are only included and sent if they too have the form attribute.

[estelle]

@Josh-Cena I am not saying my solution is the right one, but i do think we should inform the reader that the result may not be obvious. Suggestions?

[Josh-Cena]

Suggested change

The collection of form control elements includes {{htmlelement("button")}}, {{htmlelement("fieldset")}}, {{htmlelement("input")}}, {{htmlelement("object")}}, {{htmlelement("output")}}, {{htmlelement("select")}}, and {{htmlelement("textarea")}} elements whose form owner is the {{htmlelement("form")}} element.

The collection returned by {{domxref("HTMLFormElement.elements")}} includes {{htmlelement("button")}}, {{htmlelement("fieldset")}}, {{htmlelement("input")}}, {{htmlelement("object")}}, {{htmlelement("output")}}, {{htmlelement("select")}}, and {{htmlelement("textarea")}} elements whose form owner is the {{htmlelement("form")}} element. This collection is unrelated to what would be sent when the form is submitted.

If the intention is to document the dissociation between what's included and what's submitted, then sure we could keep this paragraph, but make that purpose more salient. Also: (1) we should add this caveat to HTMLFormElement.elements as well, because that's the actually relevant documentation page. (2) the HTMLFormElement.elements page talks about <input type="image"> not being included, and form-associated custom elements being included, which should be mentioned here as well. Alternatively we could just replace this list with a link saying "See HTMLFormElement.elements for the list of elements included", which I prefer because it makes it clear that this collection itself doesn't control what can be inside it.

[estelle]

replaced with #41096