JavaScript: The Definitive Guide, Fourth Edition

Name

Element.getElementsByTagName( ) — find descendant elements with a specified tag name

Availability

DOM Level 1 Core

Synopsis

Node[] getElementsByTagName(String name);

Arguments

name

The tag name of the desired elements, or the value “*” to specify that all descendant elements should be returned, regardless of their tag names.

Returns

An array (technically, a NodeList) of Element objects that are descendants of this element and have the specified tag name.

Description

This method traverses all descendants of this element and returns an array (really a NodeList object) of Element nodes representing all document elements with the specified tag name. The elements in the returned array appear in the same order in which they appear in the source document.

Note that the Document interface also has a getElementsByTagName( ) method that works just like this one but that traverses the entire document, rather than just the descendants of a single element. Do not confuse this method with HTMLDocument.getElementsByName( ), which searches for elements based on the value of their name attributes rather than by their tag names.

Example

You can find all <div> tags in a document with code like the following:

var divisions = document.body.getElementsByTagName("div");

And you can find all <p> tags within the a <div> tag with code like this:

var paragraphs = divisions[0].getElementsByTagname("p");

See Also

Document.getElementById( ), Document.getElementsByTagName( ), HTMLDocument.getElementsByName( )