Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Revision 802731 of Element.getElementsByTagName()

  • Revision slug: Web/API/Element/getElementsByTagName
  • Revision title: Element.getElementsByTagName()
  • Revision id: 802731
  • Created:
  • Creator: stompychum
  • Is current revision? No
  • Comment Minor copyedit in Compatibility notes

Revision Content

{{ APIRef("DOM") }}

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, the HTMLCollection 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 reflect the spec change.

[2] Initially, this method was returning a {{domxref("NodeList")}}; it was then changed to reflect the spec change.

Revision Source

<p>{{ APIRef("DOM") }}</p>

<p>The <code><strong>Element.getElementsByTagName()</strong></code> method returns a live {{domxref("HTMLCollection")}} of elements with the given <a href="/en/DOM/element.tagName" title="en/DOM/element.tagName">tag name</a>. The subtree underneath the specified element is searched, excluding the element itself. The returned list is <em>live</em>, meaning that it updates itself with the DOM tree automatically. Consequently, there is no need to call several times <code>Element.getElementsByTagName()</code> with the same element and arguments.</p>

<p>When called on an HTML element in an HTML document, <code>getElementsByTagName</code> 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.</p>

<p><code>Element.getElementsByTagName</code> is similar to {{domxref("Document.getElementsByTagName()")}}, except that its search is restricted to those elements which are descendants of the specified element.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox"><code><em>elements</em> = <em>element</em>.getElementsByTagName(<em>tagName</em>)</code></pre>

<ul>
 <li><code>elements</code> is a <em>live</em> {{domxref("HTMLCollection")}} of found elements in the order they appear in the sub-tree. If no elements were found, the <code>HTMLCollection</code> is empty.</li>
 <li><code>element</code> 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.</li>
 <li><code>tagName</code> is the qualified name to look for. The special string <code>"*"</code> represents all elements. For compatibility with XHTML, lower-case should be used.</li>
</ul>

<h2 id="Example">Example</h2>

<pre class="brush: js">// 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 &lt; cells.length; i++) { 
    var status = cells[i].getAttribute("data-status"); 
    if ( status == "open" ) { 
        // grab the data 
    }
}
</pre>

<h2 id="Browser_Compatibility" name="Browser_Compatibility">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('DOM WHATWG', '#dom-element-getelementsbytagname', 'Element.getElementsByTagName()')}}</td>
   <td>{{Spec2('DOM WHATWG')}}</td>
   <td>Changed the return value from {{domxref("NodeList")}} to {{domxref("HTMLCollection")}}</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM3 Core', 'core.html#ID-1938918D', 'Element.getElementsByTagName()')}}</td>
   <td>{{Spec2('DOM3 Core')}}</td>
   <td>No change from {{SpecName('DOM2 Core')}}</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 Core', 'core.html#ID-1938918D', 'Element.getElementsByTagName()')}}</td>
   <td>{{Spec2('DOM2 Core')}}</td>
   <td>No change from {{SpecName('DOM1')}}</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM1', 'level-one-core.html#ID-1938918D', 'Element.getElementsByTagName()')}}</td>
   <td>{{Spec2('DOM1')}}</td>
   <td>Initial definition</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table" height="86" width="951">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>1.0 [2]</td>
   <td>{{ CompatVersionUnknown() }} [1]</td>
   <td>5.5</td>
   <td>{{ CompatVersionUnknown() }} [2]</td>
   <td>{{ CompatVersionUnknown() }} [2]</td>
  </tr>
  <tr>
   <td>getElementsByTagName("*")</td>
   <td>1.0</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>6.0</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }} [1]</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Prior to Firefox 19, this method was returning a {{domxref("NodeList")}}; it was then changed to reflect the spec change.</p>

<p>[2] Initially, this method was returning a {{domxref("NodeList")}}; it was then changed to reflect the spec change.</p>
Revert to this revision