Document.getElementsByName()

  • Revision slug: DOM/document.getElementsByName
  • Revision title: document.getElementsByName
  • Revision id: 68458
  • Created:
  • Creator: George3
  • Is current revision? No
  • Comment /* Notes */ 'bug' template instead of URL, DOM:NodeList instead of NodeList

Revision Content

{{ DomRef() }}

Summary

Returns a list of elements with a given name in the (X)HTML document.

Syntax

elements = document.getElementsByName(name) 
  • elements is a NodeList of elements.
  • name is the value of the name attribute of the element.

Example

// return some of the forms 
//<form name="up"><input type="text"/></form> 
//<form name="up"><input type="text"/></form> 
//<form name="down"><input type="text"/></div> 
//<form name="down"><input type="text"/></div> 
up_forms = document.getElementsByName("up"); 
dump(up_forms.item(0).tagName); // returns "div"

Notes

The name attribute is only applicable to (X)HTML documents.

Although the standard behavior is supposed to only return name attributes in XHTML for form controls, this behavior is not implemented per {{ Bug("242808") }}. (In XHTML, the method returns all elements with a name attribute, such as <meta> or <object> or even if 'name' is placed on elements which do not support a name attribute at all. This is standard behavior for HTML, but not for XHTML.)

document.getElementsByName returns a NodeList of all the elements with a given value for the name attribute. Unlike getElementsByTagName, which uses the name of the tag itself, this method applies only to elements that have been given a value for their name attribute.

Name attribute availability

The name attribute has gone through a period of changes.

As of XHTML 1.0:

In XHTML 1.0 Transitional:

  • <frame> was dropped

In XHTML 1.0 Strict:

  • 'name' was dropped from <img> and <form>
  • <iframe> itself was dropped

As of XHTML 1.1:

  • the name attribute was dropped entirely for <a> and <map> (though it can be included with the deprecated Name Identification module), leaving name only on the following elements for which they have always been allowed:
<meta>, <object>, <param> (required), <input> ('name' required for all types besides submit and reset types), <select>, <textarea>, <button>

This method might be questionable for use given the above changes between document types and the current non-standard behavior for this method in XHTML.

Specification

DOM Level 2 HTML: getElementsByName

{{ languages( { "fr": "fr/DOM/document.getElementsByName", "ja": "ja/DOM/document.getElementsByName", "pl": "pl/DOM/document.getElementsByName" } ) }}

Revision Source

<p>
{{ DomRef() }}
</p>
<h3 name="Summary"> Summary </h3>
<p>Returns a list of elements with a given <code><a href="en/DOM/element.name">name</a></code> in the (X)HTML document.
</p>
<h3 name="Syntax"> Syntax </h3>
<pre class="eval"><i>elements</i> = document.getElementsByName(<i>name</i>) 
</pre>
<ul><li> <code>elements</code> is a <a href="en/NodeList">NodeList</a> of elements.
</li><li> <code>name</code> is the value of the <code>name</code> attribute of the element.
</li></ul>
<h3 name="Example"> Example </h3>
<pre>// return some of the forms 
//&lt;form name="up"&gt;&lt;input type="text"/&gt;&lt;/form&gt; 
//&lt;form name="up"&gt;&lt;input type="text"/&gt;&lt;/form&gt; 
//&lt;form name="down"&gt;&lt;input type="text"/&gt;&lt;/div&gt; 
//&lt;form name="down"&gt;&lt;input type="text"/&gt;&lt;/div&gt; 
up_forms = document.getElementsByName("up"); 
dump(up_forms.item(0).tagName); // returns "div"
</pre>
<h3 name="Notes"> Notes </h3>
<p>The <a href="en/DOM/element.name">name</a> attribute is only applicable to (X)HTML documents. </p><p>Although the standard behavior is supposed to only return name attributes in XHTML for form controls, this behavior is not implemented per {{ Bug("242808") }}. (In XHTML, the method returns all elements with a name attribute, such as &lt;meta&gt; or &lt;object&gt; or even if 'name' is placed on elements which do not support a name attribute at all. This is standard behavior for HTML, but not for XHTML.)
</p><p><code>document.getElementsByName</code> returns a <a href="en/DOM/NodeList">NodeList</a> of all the elements with a given value for the name attribute. Unlike <a href="en/DOM/document.getElementsByTagName">getElementsByTagName</a>, which uses the name of the tag itself, this method applies only to elements that have been given a value for their <code>name</code> attribute.
</p>
<h3 name="Name_attribute_availability"> Name attribute availability </h3>
<p>The name attribute has gone through a period of changes.
</p><p>As of XHTML 1.0:
</p>
<ul><li> the use of the name attribute was deprecated on &lt;a&gt;, &lt;applet&gt;, &lt;form&gt;, &lt;frame&gt;, &lt;iframe&gt;, &lt;img&gt;, and &lt;map&gt;<a class="external" href="http://www.w3.org/TR/xhtml1/#h-4.10">
</a></li><li><a class="external" href="http://www.w3.org/TR/xhtml1/#h-4.10"> the &lt;applet&gt; tag itself was itself deprecated
</a></li></ul><a class="external" href="http://www.w3.org/TR/xhtml1/#h-4.10">
<p>In XHTML 1.0 Transitional:
</p>
<ul><li> &lt;frame&gt; was dropped
</li></ul>
<p>In XHTML 1.0 Strict:
</p>
<ul><li> 'name' was dropped from &lt;img&gt; and &lt;form&gt;
</li><li> &lt;iframe&gt; itself was dropped
</li></ul>
<p>As of XHTML 1.1:
</p>
<ul><li> the name attribute was dropped entirely for &lt;a&gt; and &lt;map&gt; (though it can be included with the deprecated Name Identification module), leaving name only on the following elements for which they have always been allowed:
</li></ul>
<blockquote>&lt;meta&gt;, &lt;object&gt;, &lt;param&gt; (required), &lt;input&gt; ('name' required for all types besides submit and reset types), &lt;select&gt;, &lt;textarea&gt;, &lt;button&gt;</blockquote>
<p>This method might be questionable for use given the above changes between document types and the current non-standard behavior for this method in XHTML.
</p>
<h3 name="Specification"> Specification </h3>
</a><p><a class="external" href="http://www.w3.org/TR/xhtml1/#h-4.10"></a><a class="external" href="http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-71555259">DOM Level 2 HTML: getElementsByName</a>
</p>{{ languages( { "fr": "fr/DOM/document.getElementsByName", "ja": "ja/DOM/document.getElementsByName", "pl": "pl/DOM/document.getElementsByName" } ) }}
Revert to this revision