setAttribute (W3C DOM Core method)

element.setAttribute('rel', 'me');

<a href="http://www.brothercake.com/">brothercake</a>

<a href="http://www.brothercake.com/" rel="me">brothercake</a>

Description

Set a new attribute with the specified name and value to this element.

If an attribute already exists with the specified name, its value is replaced.

When setting a value, the value is not parsed, so any entity references or other markup will be treated as literal text. To create an attribute containing entities the specification suggests to create an Attr node with appropriate Text and EntityReference nodes as children, then add it to an element using setAttributeNode, however in practise this rarely works (see Attr for details).

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

Be careful with camel-cased attribute names

You should be careful using camel-cased names in code intended for all browsers, because in Opera in XHTML mode, setting an attribute with a camel-cased name may affect its corresponding DOM property. For example, if you set an attribute called tabIndex to any value, it will have the effect of resetting the tabIndex property to 0 (its default value), removing the original tabindex attribute entirely, and creating a new attribute with the name tabIndex and the specified string value.

This behavior is probably down to an inconsistency in how case-sensitivity is handled in XHTML mode. In other browsers (Firefox and Safari) doing this will create a new attribute called tabIndex, while leaving the original tabindex attribute and its corresponding tabIndex property unchanged.

This note only applies to these browsers in XHTML mode — in HTML mode2 the name argument is case-insensitive, so tabIndex is treated as tabindex.

Additionally, IE in HTML cannot set the type attribute of an input element — attempting to do so will throw an error (This command is not supported). It also can’t set the style attribute (doing so simply has no effect), and cannot set event-handling attributes as strings (to do so has no effect, unless that element already has an event-handling attribute of the same name, in which the case the operation to set a new one will remove the old one, leaving nothing — although getAttribute will subsequently return the string value that was set, there won’t actually be an active event handler on the element). IE can, however, set event-handling attributes if a function is passed as the value argument, rather than a string:

element.setAttribute('onclick', function() { alert("this works!"); });

Finally, if this method is used to set the src attribute of an image, the value that’s subsequently returned from getAttribute will be a fully qualified URI; this is the same as its behavior when retrieving an src that’s been set in static HTML. However when setting the href of a link, the value that’s subsequently returned will be the literal value that was set; this is different from its behavior with static HTML in which the value is returned as a qualified URI.

How do I know if it works?

Establishing whether this method works as expected is particularly difficult, because it’s possible to set an attribute of any name at all, though it may not be the attribute you expect. For example, in Internet Explorer you can still set an attribute called class, and subsequently retrieve it with getAttribute(‘class’), but it will not correspond with the className property — it will be an entirely separate attribute that makes no visual difference to the element.

In all browsers an attribute which evaluates to a boolean (such as disabled) can only be set to true — setting it to false has no effect. This is correct behavior, and is because such attributes should only have one possible value (ie. disabled=”disabled”), or are not defined (so negating them should be done with removeAttribute). In Opera 9.5, Firefox and Safari the attribute value will subsequently return as false but the element will still be disabled, in Opera 9.0 the value will continue to return as disabled, and in Internet Explorer the value will continue to return as boolean true; these are accurate reflections of the state of the element, even if they are a little confusing! However since IE considers these attributes to have an actual boolean value, the value can be toggled (and the element disabled and enabled accordingly) by setting it as a boolean rather than a string:

element.setAttribute('disabled', false);

Internet Explorer implements a second argument to setAttribute, which is a case-sensitivity flag that can take the value 0 (case-insensitive) or 1 (default, case-sensitive). This argument works as expected in IE, and does not affect any other browser.