Element.getElementsByTagName

  • Revision slug: DOM/element.getElementsByTagName
  • Revision title: element.getElementsByTagName
  • Revision id: 316645
  • Created:
  • Creator: Bzbarsky
  • Is current revision? No
  • Comment

Revision Content

{{ DomRef() }}

Summary

Returns a list 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.

Syntax

elements = element.getElementsByTagName(tagName)

  • elements is a live HTMLCollection (but see the note below) of found elements in the order they appear in the subtree. 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.
Note: While the W3C DOM 3 Core specification says elements is a NodeList that was simply because of a an attempt to have the "core" specification not depend on the "html" specification at that time.  The DOM 4 draft says that elements is an HTMLCollection.  This method returns a HTMLCollection both in Gecko and Internet Explorer. Opera returns a NodeList, but with a namedItem method implemented, which makes it similar to a HTMLCollection. As of January 2012, only in WebKit browsers the returned value is a pure NodeList. See bug 14869 for details.

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 
    }
}

Notes

When called on an HTML element in an HTML document, getElementsByTagName lowercases its argument before proceeding. This is undesirable when trying to match camelCase SVG elements in a subtree in an HTML document. {{ Domxref("element.getElementsByTagNameNS") }} works in that case. See also {{ Bug(499656) }}.

element.getElementsByTagName is similar to document.getElementsByTagName, except that its search is restricted to those elements which are descendants of the specified element.

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 1.0 {{ CompatVersionUnknown() }} 5.5 {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }}
getElementsByTagName("*") 1.0 {{ CompatVersionUnknown() }} 6.0 {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }}

Specifications

{{ languages( { "es": "es/DOM/element.getElementsByTagName", "fr": "fr/DOM/element.getElementsByTagName", "ja": "ja/DOM/element.getElementsByTagName", "pl": "pl/DOM/element.getElementsByTagName" } ) }}

Revision Source

<p>{{ DomRef() }}</p>
<h2 id="Summary">Summary</h2>
<p>Returns a list 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>
<h2 id="Syntax">Syntax</h2>
<p><code><em>elements</em> = <em>element</em>.getElementsByTagName(<em>tagName</em>)</code></p>
<ul>
  <li><code>elements</code> is a <em>live</em> <a href="/en/DOM/HTMLCollection" title="en/DOM/NodeList"><code>HTMLCollection</code></a> (but see the note below) of found elements in the order they appear in the subtree. 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>
<div class="note">
  <strong>Note:</strong> While the W3C DOM 3 Core specification says <code>elements</code> is a <code>NodeList</code> that was simply because of a an attempt to have the "core" specification not depend on the "html" specification at that time.&nbsp; The DOM 4 draft says that <code>elements</code> is an <code>HTMLCollection</code>.&nbsp; This method returns a <code>HTMLCollection</code> both in Gecko and Internet Explorer. Opera returns a <code>NodeList</code>, but with a <code>namedItem</code> method implemented, which makes it similar to a <code>HTMLCollection</code>. As of January 2012, only in WebKit browsers the returned value is a pure <code>NodeList</code>. See <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=14869" title="https://bugzilla.mozilla.org/show_bug.cgi?id=14869">bug 14869</a> for details.</div>
<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="Notes">Notes</h2>
<p>When called on an HTML&nbsp;element in an HTML&nbsp;document, <code>getElementsByTagName</code> lowercases its argument before proceeding. This is undesirable when trying to match camelCase SVG elements in a subtree in an HTML&nbsp;document. {{ Domxref("element.getElementsByTagNameNS") }} works in that case. See also {{ Bug(499656) }}.</p>
<p><code>element.getElementsByTagName</code> is similar to <a href="/en/DOM/document.getElementsByTagName" title="en/DOM/document.getElementsByTagName">document.getElementsByTagName</a>, except that its search is restricted to those elements which are descendants of the specified element.</p>
<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <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</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>5.5</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</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() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id="Specifications">Specifications</h2>
<ul>
  <li><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-1938918D">DOM Level 2 Core: Element.getElementsByTagName </a></li>
  <li><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#apis-in-html-documents">HTML 5: APIs in HTML documents</a></li>
</ul>
<p>{{ languages( { "es": "es/DOM/element.getElementsByTagName", "fr": "fr/DOM/element.getElementsByTagName", "ja": "ja/DOM/element.getElementsByTagName", "pl": "pl/DOM/element.getElementsByTagName" } ) }}</p>
Revert to this revision