I’ve been thinking about how to present attributes for HTML input elements, and am finding our docs confusing here.
I’m bringing this up not for mindless nit-picking, but mostly to check my understanding. Have I misunderstood the way these pages are supposed to be used, or is there really a problem here? And how would we like this information to be presented, in an ideal world?
For a given input element there seem to be three different places that possible attributes are listed:
(1) Common attributes
This is https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Attributes. It says:
"Since every <input> element, regardless of type, is based on the HTMLInputElement interface, they technically all share the exact same set of attributes. However, in reality, many attributes only function on specific input types, and some input types support very few of these attributes. In addition, some input types handle certain attributes in special ways.
Here, you’ll find information about the individual attributes which are common to all <input> element types"…
It lists:
- autocomplete
- autofocus
- disabled
- form
- list
- name
- readonly
- required
- tabindex
- type
- value
(2) Supported Common Attributes
In each individual input element type page, there’s a blue box with a row labelled “Supported Common Attributes”. This lists attributes, linked to attribute description in the main input page, with a link like https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autocomplete.
(3) Additional attributes
In each individual page there’s a section headed “Additional attributes” which says something like:
“In addition to the attributes that operate on all <input> elements regardless of their type, url inputs support the following attributes”
…then lists some more attributes.
So first this is weird because, didn’t (1) say it includes “attributes which are common to all <input> element types”. So why is the blue box “Supported Common Attributes” telling me that only some of them are supported for a given type?
Well, let’s explain this by saying that some of the attributes in (1) are not really common.
Then I would expect that:
-
all attributes listed in (2) should be present in (1). This is of course strongly implied by the fact that the attributes listed in (2) are linking to the list in (1).
-
none of the attributes listed in (3) should be in either (2) or (1). That’s because (1) says it lists “the individual attributes which are common to all <input> element types”, while (3) says it lists attributes “In addition to the attributes that operate on all <input> elements regardless of their type”.
In fact neither of these things seem to be true, and I can’t see a pattern at all for when attributes appear in one list or another (or two, or all three).
For example:
-
valueappears in (1). It:
Very often, attributes listed in (2) aren’t in (1), meaning that the links are broken (For example, all the links in https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/image, but in most pages at least some of these links are broken).
Often (2) and (3) have a considerable (but usually not complete) overlap, and often these overlapping attributes are not also in (1).
It’s not clear why for a single input element type, some attributes appear in (2) and (3), while some appear only in (3). For example, email lists maxLength in both (2) and (3) (but not (1)), whereas it lists spellcheck only in (3). Why? I have no idea.
From a user point of view the main question seems to be “for this particular input element, which attributes can I actually use?”.
The best approach for that question seems to be to scrap all these separate lists, and have each input element type have its own “Attributes” section listing all the attributes that it supports. It could have some boilerplate at the top explaining that, technically, it can support the complete superset of input element attributes, but that only the subset below is relevant for this type.
Then in the main input page we could just list the complete superset, with some boilerplate at the top saying that although technically all input element types support all of these attributes, only a subset is actually useful for each individual type.