Anne van Kesteren



  1. $() / $$()
  2. document.match() / document.matchAll()
  3. / document.selectAll()
  4. document.matchSingle() / document.matchAll()
  5. document.matchSelectors() / document.matchAllSelectors()
  6. document.getElementBySelector() / document.getElementsBySelector()
  7. document.getElementBySelectors() / document.getElementsBySelectors()
  8. document.getElementByGroupOfSelectors() / document.getElementsByGroupOfSelectors()
  9. … / document.matchCSS()


  1. Quite confusing... Which language is this?

    Posted by Arjan Eising at

  2. See the Selectors API naming debate for some amusing background information.

    Posted by Anne van Kesteren at

  3. 1 is what JS libraries use because names are too long. 4-8 are too long (which will result in 1). 9 doesn't look like a complete proposal. 3 is in conflict with XPath.

    That leaves 2.

    Posted by zcorpan at

  4. I demand to know why you haven't considered getElementsByGroupOfSelectorsResultingInANodeListForUseInComputerProgramsAndEnterpriseMashupsAndMySpacePages()

    Posted by Robert Sayre at

  5. Personally I prefer these as they are consistent with getElementById() and getElementsByTagName():

    The second pair is not really necessary though…as it can be done by called the former pairs multiple times.

    Posted by minghong at

  6. 7/2 and 8/2 are the only consistent choices I can see. As for 1. I presume you are joking Anne? The choice to try to make JavaScript look like line noise, err -- Perl, is IMNSHO an offense for which people should be condemned to write all of their code in Whitespace.

    Posted by Arve at

  7. I meant 6/2 and 7/2. The options in point eight are a tad verbose.

    Posted by Arve at

  8. I, too, think document.getElementsBySelector() makes the most sense.


    Posted by Laurens Holst at

  9. By the way, why a getElementBySelector in addition to one for multiple matches? There’s no getElementByTagName either isn’t there, people can just take the first result, and the implementation can optimise it by using lazy evaluation if needed.


    Posted by Laurens Holst at

  10. getElementsBySelector() would be perfect and I agree with Laurens on the usefulness of getElementBySelector().

    It's consistent, easy to remember. Reading throught the discussion I can only say, shorter will never be short enough people will alias anyway. Consistency is very useful for both people new to the language and people who are very familiar with the established getElement* naming convention.

    Also, a live nodelist sounds much better then a static one although I'm not sure of the difference. It seems they differ enough to let it be an implementation problem if it were a live nodelist.

    But Anne I'm sure we all would like you opinion about it (I already known as I read the discussion) as it's you who will be writing the spec.

    Posted by Jaap at

  11. getElementsBySelector() is the best. BTW, I don't get why we need pair for it?

    Posted by FataL at

  12. I do enjoy $() and $$() in prototype, as they're nice and short. The problem is that they are impossible to find documentation for. Google much prefers letters.

    Posted by Daniel Morrison at

  13. Daniel Morrison, you could try Google Code Search.

    Posted by Blaise at

  14. I assume you need a pairing because you can have elements with multiple selectors, and selectors with multiple elements.

    Posted by Simon Jessey at

  15. This should definitely be getElementsBySelector. And it should return a live nodelist. Not because these choices are good; they actually suck, compared to some others being considered. However, you’re not going to be changing the existing DOM API, so please please stick to its already established naming pattern. One PHP is enough for this planet.

    Leave provision of shorter names and saner semantics in the realm of the JS libraries. You are not going to obsolete them just by adding useful bits to the DOM API anyway.

    Posted by Aristotle Pagaltzis at

  16. There is a problem with getElementBySelector / getElementsBySelector that I haven't seen anyone mention - the two functions look almost identical. It'll be very easy to misread them which makes code maintenance much harder.

    Posted by Daniel James at

  17. One reason for considering the alternative naming is that with this you no longer need getElementsByTagName and getElementById in theory. Also, another problem is that getElementsBySelector in inaccurate. You actually pass a group of selectors which allows you to do things like: document.matchAll("foo, bar") to get all foo and bar elements in document order.

    It’s not clear to me by the way how lazy evaluation would work here. Especially considering the list is not live. The reason the list is not live by the way is that implementors gave feedback that such a thing would not be feasible. No fun in having a specification without implementations.

    Posted by Anne van Kesteren at

  18. Ah. Well, if making it consistent is not an option, then, of course, it should be inconsistent on all counts; in which case I’d vote for select/selectAll. (The match/matchAll pair is OK too, but less preferrable; “match” is something I’d name a boolean function.)

    Posted by Aristotle Pagaltzis at

  19. Actually you would still need getElementsByTagName in cases a live node list is preferred. I also expect that getElementById will be the preferred way of getting a specific node by Id as it probably will be faster (no need for parsing an expression).

    I don't like matchAll at all (no pun) it sounds a lot like a regex matching thing, witch it's not. getElementsBySelectors would then still be more accurate and consistent. But in the end it's all up to you. Pretty cool that you have the final decision about what thousands (millions?) of webdevelopers get to type when coding for the DOM in the far future.

    Posted by Jaap at

  20. I don't like the long, verbose method names, and match/matchAll isn't semantic enough for me, it definitely feels like that's referring to a regular expression.

    Personally, I'd prefer to see something like document.getNodes() / document.getNode(). It says that it's getting nodes. It says that it is the only method that should be used to get nodes. It follows the established get* naming convention. It also fits in with other standard DOM methods like cloneNode, obj.childNodes, obj.parentNode, et al.

    I also agree that getElementById and getElementsByTagName should be obsoleted by this/these method(s). I hate passionately typing out the current method names.

    I can't really conceive how this new method would be any slower than these old methods. If it really would be slowing, it'd be so marginal so as to not be noticeable.

    Please keep it short, simple, and descriptive of what's its purpose is. And please, please make it a live node list, or provide a toggle for making it either static or live.

    Posted by Richard York at

  21. And please, please make it a live node list, or provide a toggle for making it either static or live.

    What’s the use case? There are reasonable people who think live lists in the DOM are a design bug and comatose lists (the list is not live, but it references live tree nodes instead of copying them) is the right way to go.

    Posted by Henri Sivonen at

  22. Oh, and I think less typing is good (less strain for the hands) and making all related methods start with “get” or “getElement” is bad for autocomplete (if, down the road, we get autocomplete for JavaScript). I like matchCSS, even though I do agree that getElementsBySelectors would be more consistent.

    Posted by Henri Sivonen at

  23. “get” or “getElement” is bad for autocomplete

    getNodes isn't really. You have to type four letters. Or really just one letter, and you get the auto complete list. And if this method does indeed deprecate the other ones, then you won't really have to worry about those, will you? Because, you see, it already does id and name selection.

    What’s the use case?

    Are you serious? I can think of plenty of caching scenarios where that'd be useful and result in less code, that more than likely would preform better. Such as an XMLHttpRequest file management app that I wrote. I could make one call to get all of the file nodes, instead of every time the file nodes change. If the node list is live, then the current nodes are always in a cached array.

    Of course, I'm not an implementor, if it doesn't end up that way, I'd still be happy. But my programming mind is having trouble envisioning how it could be so hard to pull that off or make that an option. Perhaps there's some fringe use cases that I'm not taking into consideration.

    Anyway, rather than going back and forth in Anne's comment section, I think I'll just leave it up to him to weigh the pros and cons of each suggestion and update the spec as necessary.

    Posted by Richard York at

  24. Or really just one letter, and you get the auto complete list. And if this method does indeed deprecate the other ones, then you won't really have to worry about those, will you?

    Well, autocomplete implementations tend to show all the old stuff as well. With JS the editor cannot know the runtime type of variables, so you’d likely see much more stuff stuff in an autocomplete menu than in a Java or C# IDE. (I don’t know of any JS editor that had autocomplete, BTW, so I don’t really believe the “autocomplete will save us” argument anyway.)

    What’s the use case?

    Are you serious?


    Iterating over live lists is trouble if you change the document during iteration. Moreover, the implementation of query-based live lists leads to hairy code. I encourage you to read the source of an open source DOM implementation of your choice.

    Posted by Henri Sivonen at

  25. Until someone can convince implementors to make it a live list it’s not debatable. I thought I made that perfectly clear.

    Posted by Anne van Kesteren at

  26. getElementsBySelector() is most consistent with the existing DOM methods and if you want to extend it to allow multiple selectors, it's possible to overload the method by allowing an array of selector strings to be passed as arguments. You don't need a separate method for that, and if you only want one element, you just do getElementsBySelector('...')[0] anyway.

    Posted by Asbjørn Ulsberg at

  27. Pretty cool that you have the final decision about what thousands (millions?) of webdevelopers get to type when coding for the DOM in the far future.

    Actually, the working group as a whole has to choose, and that basically means wading through all the comments saying "XYZ" is totally unacceptable until we either find enough that provide really compelling reasons ("it's too long", "consistency is important", and "people use $$() anyway so it won't matter" pretty much seem to cancel each other out so far), or more likely find the one that is least hated, and spend the rest of our lives as the people who made the stupid decision to call it whatEver().

    And with respect to Robert's suggestion, we did consider getSomeKindOfThingThatMightBeStableByProvidingAMatchingPatternThatUsesTheSameSyntaxAsCSSSelectorsButIsSpecifiedSomewhereElseAsMerelyBeingSyntacticallyAndSemanticallyCompatible() but rejected it in the end because we couldn't agree on whether it is reasonable to call the Selectors specification from the CSS group CSSSelectors in a method name... If only we had your proposal earlier we could have had the spec to last call in time to actually consider comments at our next meeting :(

    (Seriously, the naming issue might seem stupid, but as well as provoking a remarkable amount of discussion it has kept the spec back by a couple of months. On the other hand, getting it wrong would probably have been just as counter-productive :( ).

    Hey Anne, if you insist on XHTML why not use a quoting tool that gets it right?

    Posted by Chaals at

  28. Remove the "get" from method names, it's useless and doesn't carry additional semantics. Just "xy.elementsBySelector()" does the job as well. I'll never understand why all the world keeps copying the "gets" introduced by Java.

    Posted by Christian at

  29. I agree with Christian. If you really need brevity, drop the filler and leave the substance. I propose ".nodeBySelector()" and ".nodelistBySelector()"

    Posted by Doug Schepers at