{{ APIRef() }}
The Element.getElementsByTagName()
method returns a live {{domxref("HTMLCollection")}} of elements with the given tag name. The subtree underneath the specified element is searched, excluding the element itself. The returned list is live, meaning that it updates itself with the DOM tree automatically. Consequently, there is no need to call several times Element.getElementsByTagName()
with the same element and arguments.
When called on an HTML element in an HTML document, getElementsByTagName
put its argument in lower case before proceeding. This is undesirable when trying to match camel-cased SVG elements in a sub-tree in an HTML document. {{ domxref("Element.getElementsByTagNameNS()") }} works in that case.
Element.getElementsByTagName
is similar to {{domxref("Document.getElementsByTagName()")}}, except that its search is restricted to those elements which are descendants of the specified element.
Syntax
elements = element.getElementsByTagName(tagName)
elements
is a live {{domxref("HTMLCollection")}} of found elements in the order they appear in the sub-tree. If no elements were found, theHTMLCollection
is empty.element
is the element from where the search should start. Note that only the descendants of this element are included in the search, but not the element itself.tagName
is the qualified name to look for. The special string"*"
represents all elements. For compatibility with XHTML, lower-case should be used.
Example
// check the alignment on a number of cells in a table. var table = document.getElementById("forecast-table"); var cells = table.getElementsByTagName("td"); for (var i = 0; i < cells.length; i++) { var status = cells[i].getAttribute("data-status"); if ( status == "open" ) { // grab the data } }
Specifications
Specification | Status | Comment |
---|---|---|
{{SpecName('DOM WHATWG', '#dom-element-getelementsbytagname', 'Element.getElementsByTagName()')}} | {{Spec2('DOM WHATWG')}} | Changed the return value from {{domxref("NodeList")}} to {{domxref("HTMLCollection")}} |
{{SpecName('DOM3 Core', 'core.html#ID-1938918D', 'Element.getElementsByTagName()')}} | {{Spec2('DOM3 Core')}} | No change from {{SpecName('DOM2 Core')}} |
{{SpecName('DOM2 Core', 'core.html#ID-1938918D', 'Element.getElementsByTagName()')}} | {{Spec2('DOM2 Core')}} | No change from {{SpecName('DOM1')}} |
{{SpecName('DOM1', 'level-one-core.html#ID-1938918D', 'Element.getElementsByTagName()')}} | {{Spec2('DOM1')}} | Initial definition |
Browser compatibility
{{ CompatibilityTable() }}
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | 1.0 [2] | {{ CompatVersionUnknown() }} [1] | 5.5 | {{ CompatVersionUnknown() }} [2] | {{ CompatVersionUnknown() }} [2] |
getElementsByTagName("*") | 1.0 | {{ CompatVersionUnknown() }} | 6.0 | {{ CompatVersionUnknown() }} | {{ CompatVersionUnknown() }} |
Feature | Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | {{ CompatVersionUnknown() }} | {{ CompatVersionUnknown() }} [1] | {{ CompatVersionUnknown() }} | {{ CompatVersionUnknown() }} | {{ CompatVersionUnknown() }} |
[1] Prior to Firefox 19, this method was returning a {{domxref("NodeList")}}; it was then changed to reflects the spec change.
[2] Initially, this method was returning a {{domxref("NodeList")}}; it was then changed to reflect the spec change.