document.getElementsByTagName

  • Revision slug: DOM/document.getElementsByTagName
  • Revision title: document.getElementsByTagName
  • Revision id: 51677
  • Created:
  • Creator: Marcoos
  • Is current revision? No
  • Comment 78 words added

Revision Content

{{ DomRef() }}

Summary

Returns a NodeList of elements with the given tag name. The complete document is searched, including the root node. The returned NodeList is live, meaning that it updates itself automatically to stay in sync with the DOM tree without having to call document.getElementsByTagName again.

Syntax

var elements = document.getElementsByTagName(name);

  • elements is a live {{ domxref("NodeList") }} (but see the note below) of found elements in the order they appear in the tree.
  • name is a string representing the name of the elements. The special string "*" represents all elements.
Note: While the W3C specification says elements is a NodeList, this method returns a {{ domxref("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

In the following example getElementsByTagName starts from a particular parent element, and searches topdown recursively through the DOM from that parent element, looking for child elements matching the tag name parameter.

Note that when the node on which getElementsByTagName is invoked is not the document node, in fact the element.getElementsByTagName method is used.

<html>
<head>
<title>getElementsByTagName example</title>

<script type="text/javascript">

function getAllParaElems()
{
  var allParas = document.getElementsByTagName("p");

  var num = allParas.length;

  alert("There are " + num + " <p> elements in this document");
}


function div1ParaElems()
{
  var div1 = document.getElementById("div1")
  var div1Paras = div1.getElementsByTagName("p");

  var num = div1Paras.length;

  alert("There are " + num + " <p> elements in div1 element");
}


function div2ParaElems()
{
  var div2 = document.getElementById("div2")
  var div2Paras = div2.getElementsByTagName("p");

  var num = div2Paras.length;

  alert("There are " + num + " <p> elements in div2 element");
}

</script>
</head>

<body style="border: solid green 3px">
<p>Some outer text</p>
<p>Some outer text</p>

  <div id="div1" style="border: solid blue 3px">
    <p>Some div1 text</p>
    <p>Some div1 text</p>
    <p>Some div1 text</p>

    <div id="div2" style="border: solid red 3px">
    <p>Some div2 text</p>
    <p>Some div2 text</p>
    </div>
  </div>

<p>Some outer text</p>
<p>Some outer text</p>

<button onclick="getAllParaElems();">
 show all p elements in document</button><br />

<button onclick="div1ParaElems();">
 show all p elements in div1 element</button><br />

<button onclick="div2ParaElems();">
 show all p elements in div2 element</button>

</body>
</html>

Notes

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

document.getElementsByTagName() is similar to {{ domxref("element.getElementsByTagName()") }}, except that its search encompasses the whole document.

Specifications

Revision Source

<p>{{ DomRef() }}</p>
<h2>Summary</h2>
<p>Returns a <a href="/En/DOM/NodeList" title="En/DOM/NodeList">NodeList</a> of elements with the given tag name. The complete document is searched, including the root node. The returned NodeList is live, meaning that it updates itself automatically to stay in sync with the DOM tree without having to call <code>document.getElementsByTagName</code> again.</p> <h2>Syntax</h2>
<p><code><em>var elements</em> = document.getElementsByTagName(<em>name</em>);</code></p>
<ul> <li><code>elements</code> is a live {{ domxref("NodeList") }} (but see the note below) of found elements in the order they appear in the tree.</li> <li><code>name</code> is a string representing the name of the elements. The special string "*" represents all elements.</li>
</ul>
<div class="note"><strong>Note:</strong> While the W3C specification says <code>elements</code> is a <code>NodeList</code>, this method returns a {{ domxref("HTMLCollection") }} 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>Example</h2>
<p>In the following example <code>getElementsByTagName</code> starts from a particular parent element, and searches topdown recursively through the DOM from that parent element, looking for child elements matching the tag <code>name</code> parameter.</p>
<p>Note that when the node on which <code>getElementsByTagName</code> is invoked is not the <code>document</code> node, in fact the <a href="/en/DOM/element.getElementsByTagName" title="en/DOM/element.getElementsByTagName">element.getElementsByTagName</a> method is used.</p>
<pre class="brush: html">&lt;html&gt;
&lt;head&gt;
&lt;title&gt;getElementsByTagName example&lt;/title&gt;

&lt;script type="text/javascript"&gt;

function getAllParaElems()
{
  var allParas = document.getElementsByTagName("p");

  var num = allParas.length;

  alert("There are " + num + " &lt;p&gt; elements in this document");
}


function div1ParaElems()
{
  var div1 = document.getElementById("div1")
  var div1Paras = div1.getElementsByTagName("p");

  var num = div1Paras.length;

  alert("There are " + num + " &lt;p&gt; elements in div1 element");
}


function div2ParaElems()
{
  var div2 = document.getElementById("div2")
  var div2Paras = div2.getElementsByTagName("p");

  var num = div2Paras.length;

  alert("There are " + num + " &lt;p&gt; elements in div2 element");
}

&lt;/script&gt;
&lt;/head&gt;

&lt;body style="border: solid green 3px"&gt;
&lt;p&gt;Some outer text&lt;/p&gt;
&lt;p&gt;Some outer text&lt;/p&gt;

  &lt;div id="div1" style="border: solid blue 3px"&gt;
    &lt;p&gt;Some div1 text&lt;/p&gt;
    &lt;p&gt;Some div1 text&lt;/p&gt;
    &lt;p&gt;Some div1 text&lt;/p&gt;

    &lt;div id="div2" style="border: solid red 3px"&gt;
    &lt;p&gt;Some div2 text&lt;/p&gt;
    &lt;p&gt;Some div2 text&lt;/p&gt;
    &lt;/div&gt;
  &lt;/div&gt;

&lt;p&gt;Some outer text&lt;/p&gt;
&lt;p&gt;Some outer text&lt;/p&gt;

&lt;button onclick="getAllParaElems();"&gt;
 show all p elements in document&lt;/button&gt;&lt;br /&gt;

&lt;button onclick="div1ParaElems();"&gt;
 show all p elements in div1 element&lt;/button&gt;&lt;br /&gt;

&lt;button onclick="div2ParaElems();"&gt;
 show all p elements in div2 element&lt;/button&gt;

&lt;/body&gt;
&lt;/html&gt;
</pre>
<h2>Notes</h2>
<p>When called on an HTML document, <code>getElementsByTagName()</code> lower-cases its argument before proceeding. This is undesirable when trying to match camelCase SVG elements in a subtree in an HTML document. {{ Domxref("document.getElementsByTagNameNS()") }} works in that case. See also {{ Bug("499656") }}.</p>
<p><code>document.getElementsByTagName()</code> is similar to {{ domxref("element.getElementsByTagName()") }}, except that its search encompasses the whole document.</p>
<h2>Specifications</h2>
<ul> <li><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-A6C9094">DOM Level 2 Core: Document.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>
Revert to this revision