getAttribute (W3C DOM Core method)

Spec
Version Depr. Static
DOM1 No No
Browser support (more…)
IE5.5+ FF1.5+ SA1.3+ OP9+
Buggy Buggy Buggy Buggy
Returns
DOMString

Example

var language = document.documentElement.getAttribute('lang');

The example above retrieves the value of the lang attribute of the documentElement, and saves it to the variable language.

On an HTML page the documentElement is the root html element, so if it looked like this:

<html lang="en">

Then the language variable would have the value en.

Arguments

name (DOMString) required

The name of the attribute to retrieve.

Description

Get the value of an attribute with the specified name.

This method is for working with non-namespaced attributes; to get a namespaced attribute, use the DOM 2 getAttributeNS method instead.

Return value

The attribute value; if the attribute is not defined this method should return an empty string, however most browsers return null (see Compatibility notes above).

Compatibility

Internet Explorer Firefox Safari Opera
5.5 6.0 7.0 1.5 2.0 3.0 1.3 2.0 3.0 9.0 9.5
Buggy Buggy Buggy Buggy Buggy Buggy Buggy Buggy Buggy Buggy Buggy
Tip: This is badly broken

This method is badly broken in all browsers, particularly Internet Explorer, so you should avoid using it wherever practical.

When you need to read attributes that are also mapped to a JavaScript dot-property (such as href, style, src or event-handlers), favour that mapping instead, or consider using setAttributeNode.

Firefox, Safari and Opera return null for attributes which are not defined. They should return an empty string, but returning null is a de-facto convention (in fact earlier versions of Opera did return an empty string, but then changed to null to match this convention). Nevertheless, this behavior is considered a bug.

Note: null and empty-string both evaluate to false for DOM attributes

However in practise, the difference between null and an empty string is not significant, because both values can be tested like this:

if(!node.getAttribute('whatever'))

The assumption there is that both null and empty string will evaluate to false, and when working with DOM attributes this is a safe assumption (though it isn't a safe assumption for JavaScript in general).

Internet Explorer, Firefox, Safari and Opera 9.5 do not match attributes which are not explicitly defined but have a specific default value in this document type, such as the shape attribute of an <a> element (only Opera 9.0 gets this right).

Opera 9.0 returns an interpreted value for a style attribute, rather than the literal value. For example, this value in HTML:

style="color:green;font-size:1.5em;position:fakevalue;left:.5ex;"

gives this value from getAttribute:

color: #008000; font-size: 1.50em; left: 0.50ex;

You can see how several changes are evident — the color value has been interpreted to hexadecimal, the font-size and left values have been normalized with leading and trailing zeros, and the fake value (for which read: value it doesn't understand) has been removed. A space has also been inserted after each colon and semi-colon.

Firefox has similar, but less aggressive, behavior — leading zeros are added to float values which begin with a dot, non-understood values are removed, and a space is added after each colon and semi-colon; but float values are not otherwise normalized and colors are not interpreted.

Internet Explorer in HTML retrieving a static href attribute from a a element returns a fully-qualified URI, rather than the literal attribute value. (For a link element it correctly returns the literal value.) IE also returns a qualified URI for a static src attribute from a img element. However its behavior is different when retrieving dynamically-created attributes — see setAttribute for details.

When retrieving a style attribute, IE returns a style object, rather than an attribute value; retrieving an event-handling attribute such as onclick, it returns the contents of the event handler wrapped in an anonymous function; retrieving an attribute value which evaluates to boolean true (such as disabled or checked, when defined) or a number (such as tabindex), it returns a boolean or number (respectively), rather than a string. Since these attributes are considered by IE to have non-string values, if they're not defined they return null rather than an empty string; IE also returns null for non-defined attributes it doesn't recognise (ie. custom attribute names); other non-defined but known attributes correctly return an empty string.

To retrieve a class attribute you must refer to it as className; to retrieve a for attribute you must refer to it as htmlFor:

//these work in IE, null in others
element.getAttribute('className');
element.getAttribute('htmlFor');

This is a side-effect of the mapping of attributes to HTML DOM properties — for example, as a DOM property you always have to refer to element.className rather than element.class, because class is a reserved word1 in JavaScript. But while other browsers reconcile this by allowing string values to getAttribute to use the original attribute name, Internet Explorer does not:

//these work in others, null in IE
element.getAttribute('class');
element.getAttribute('for');

Furthermore [yeah I know, my brain is melting too] there are other attributes that can only be referred to by the camel-cased name they use for their DOM property equivalent, even though those names are not reserved words; examples of this are tabIndex, accessKey and useMap, and all table-specific attribute properties like colSpan and rowSpan.

And still there's more ...

Internet Explorer implements a second argument to getAttribute, which is supposed to control the way it behaves. The second argument is a numerical flag that can take the value 0, 1 or 2. According to MSDN:

  • 0 (default): Performs a property search that is not case-sensitive, and returns an interpolated value if the property is found.
  • 1: Performs a case-sensitive property search.
  • 2: Returns the value exactly as it was set in script or in the source document.
: “interpolated value” ..?

When it says "interpolated value" it means it won't necessarily return a string, as already noted. Notice also how it says "if the property is found" (my emphasis) — this implies that IE is not using getAttribute as a getter for node values at all, it's using it as a getter for DOM properties. This goes a long way towards explaining its aberrant behavior — if it's retrieving property values, that's why it requires property names, and why it returns a value of the applicable type.

The difference between 0 and 1 appears to be implemented as documented — attribute names are treated as case-sensitive, so a search for onClick will not match onclick. However the value 2 does not behave as documented — event-handling attributes are still returned as functions, the style attribute is now an empty string, and values which evaluate to boolean true now return 65535.2 On a more positive note, href and src attributes will now return their literal value, rather than a qualified URI. Using this second argument does not affect any other browser.

Internet Explorer in XML is a whole different kettle of fish. There are no property mappings there, so all of this errant behavior simply doesn't apply — getAttribute is a getter for Attr node values, as it should be, and behaves according to specification, with the single exception (that is the exception for all browsers) that attributes which are not defined return null rather than an empty string.

Footnotes

1 A reserved word is one that has a special meaning in JavaScript, and therefore cannot be used as the name of a variable or object. You should also avoid using reserved words as property names.

2 The number 65535 is (2^16 - 1), which is the largest possible value of a 16-bit number, represented in binary as 1111111111111111; IE's DOM implementation is derived from Microsoft COM, in which this number evaluates to VARIANT_TRUE.

User-contributed notes

Related Products