setAttribute (W3C DOM Core method)

Share this article

Returns
void
Throws
INVALID_CHARACTER_ERR, NO_MODIFICATION_ALLOWED_ERR

Example

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

The example above sets a rel attribute with the value me on an element.

So if the element in question were this HTML:

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

Then the operation above would result in this:

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

Arguments

name (DOMString) required

The name of the attribute to create or alter.

value (DOMString) required

The string value for the attribute.

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.

Frequently Asked Questions about setAttribute W3C DOM Core Method

What is the setAttribute method in JavaScript?

The setAttribute method in JavaScript is a crucial part of the Document Object Model (DOM) that allows developers to manipulate HTML elements. This method is used to add, change, or update attributes and their values in an HTML element. It takes two parameters: the attribute name and its value. For instance, if you want to change the color of a text, you can use setAttribute to modify the style attribute of the element.

How does setAttribute differ from getAttribute?

While setAttribute is used to add or change the value of an attribute, getAttribute is used to retrieve the value of an attribute. Both are methods of the Element interface in the DOM. They work together to allow developers to interact with and manipulate HTML elements.

Can I use setAttribute to modify CSS styles?

Yes, you can use setAttribute to modify CSS styles. The method can change the style attribute of an HTML element, which contains CSS properties. However, it’s important to note that using setAttribute will overwrite any existing inline styles. If you want to change a specific style property without affecting others, it’s better to use the style property of the element.

What happens if the attribute does not exist?

If the attribute does not exist, the setAttribute method will create it with the specified value. This is one of the reasons why setAttribute is so powerful: it allows developers to dynamically add attributes to HTML elements.

Can I use setAttribute with custom data attributes?

Yes, setAttribute can be used with custom data attributes. This is particularly useful when you need to store extra information that doesn’t have any visual representation. Just remember to prefix the attribute name with ‘data-‘ to comply with HTML5 standards.

Is setAttribute case-sensitive?

Yes, setAttribute is case-sensitive. This means that ‘class’ and ‘Class’ would be treated as two different attributes. Always ensure that you use the correct case when working with attributes.

Can I use setAttribute to add event handlers?

While it’s technically possible to use setAttribute to add event handlers, it’s not recommended. This is because the value of an event attribute is always a string, which means you can’t directly assign a function as the event handler. Instead, use the addEventListener method, which is specifically designed for this purpose.

Does setAttribute work with all HTML elements?

Yes, setAttribute works with all HTML elements. However, not all attributes are applicable to all elements. For example, the ‘src’ attribute is relevant for ‘img’ elements, but not for ‘p’ elements.

What are some common use cases for setAttribute?

setAttribute is commonly used to dynamically change the appearance or behavior of an HTML element. For example, you might use it to change the color of a text, add a border to an image, or change the source of an image. It’s also used to add custom data attributes.

Are there any alternatives to setAttribute?

Yes, there are alternatives to setAttribute. For example, you can directly modify the properties of an HTML element. This is often simpler and more intuitive than using setAttribute. However, setAttribute has the advantage of being able to work with any attribute, including custom data attributes.

Adam RobertsAdam Roberts
View Author

Adam is SitePoint's head of newsletters, who mainly writes Versioning, a daily newsletter covering everything new and interesting in the world of web development. He has a beard and will talk to you about beer and Star Wars, if you let him.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week