Element: setAttribute() method

Syntax

setAttribute(qualifiedName, value)

Parameters

qualifiedName

A string containing the qualified name of the attribute whose value is to be set. The attribute name is automatically converted to all lower-case when setAttribute() is called on an HTML element in an HTML document.

The format of the qualified name is prefix:localName or localName, where the parts are defined as:

prefix Optional

A "short alias" for the namespace, as returned by the prefix property.

localName

The local name of the attribute, as returned by the localName property.

value

A trusted type or string containing the value to assign to the attribute.

Trusted type instances must be passed for the following attributes when trusted types are enforced:

• Event handler content attributes, such as onclick and onload, require a TrustedScript.
• HTMLIFrameElement.srcdoc require a TrustedHTML instance.
• HTMLScriptElement.src require a TrustedScriptURL instance.
• SVGScriptElement.href require a TrustedScriptURL instance.

Trusted types are not enforced for other attributes, so a string or any trusted type may be passed.

A specified non-string value specified is converted automatically into a string.

Boolean attributes are considered to be true if they're present on the element at all. You should set value to the empty string ("") or the attribute's name, with no leading or trailing whitespace. See the example below for a practical demonstration.

Return value

None (undefined).

Exceptions

InvalidCharacterError DOMException

Thrown if either the prefix or localName is not valid:

• The prefix must have at least one character, and cannot contain ASCII whitespace, NULL, /, or > (U+0000, U+002F, or U+003E, respectively).
• The localName must have at least one character, and may not contain ASCII whitespace, NULL, /, = or > (U+0000, U+002F, U+003D, or U+003E, respectively).

Note: Earlier versions of the specification were more restrictive, requiring that the qualifiedName be a valid XML name.

TypeError

Thrown if value is passed a string instead of a trusted type object (for those attributes that require them) when Trusted Types are enforced by a CSP and no default policy is defined.

Description

setAttribute() sets the value of an attribute on the specified element. If the attribute already exists, the value is updated; otherwise a new attribute is added with the specified name and value.

To set the value of a Boolean attribute, such as disabled, you can specify any value. It doesn't matter what value you use; if the attribute is present, its value is considered to be true. By convention we enable boolean attributes by setting their value to either the name of the attribute or the empty string (""). The absence of a boolean attribute means its value is false; you must call Element.removeAttribute() to "undo" the effect of enabling a boolean attribute

To get the current value of an attribute, use getAttribute(); to remove an attribute, call removeAttribute().

Security considerations

Some attributes can be used as a vector for cross-site scripting (XSS) attacks, where potentially unsafe strings provided by a user are injected into the DOM without first being sanitized, or scripts are run that might contain malicious code.

For example, the following code shows how a potentially untrusted string provided by a user would be executed when the button is pressed.

const button = document.querySelector("button");
const potentiallyUnsafeString = "alert(1)";
button.setAttribute("onclick", potentiallyUnsafeString);

You might similarly inject untrusted HTML into the DOM by setting the HTMLIFrameElement.srcdoc attribute, or by supplying an untrusted URL to the HTMLScriptElement.src or SVGScriptElement.href attributes.

You can mitigate these issues by always assigning the appropriate trusted type object (TrustedHTML, TrustedScript, or TrustedScriptURL) for each property instead of strings, and enforcing trusted types using the require-trusted-types-for CSP directive. This ensures that the input is passed through a transformation function which might, for example, remove potentially dangerous markup from HTML before it is injected.

Examples

Setting safe attributes

This example uses setAttribute() to set the name and disabled attributes on a <button>. These attributes are both XSS-safe. Since their values are not executed or parsed as HTML into the DOM, we don't need to pass trusted types.

HTML

<div>
  <button id="reset" type="button">Reset</button>
  <button id="toggle_disabled">Toggle</button>
</div>
<button id="hello_button">Some Text</button>

button {
  height: 30px;
  width: 100px;
  margin: 1em;
}

JavaScript

First we get the button element and set its name attribute to "helloButton" using setAttribute(). To demonstrate that the attribute name did change, we then get the attribute text and display it on the button.

const helloButton = document.querySelector("#hello_button");
helloButton.setAttribute("name", "helloButton");

// Set button text to name to show the attribute changed
helloButton.innerText = helloButton.getAttribute("name");

This code is for the reset button. It simply reloads the frame.

const reloadButton = document.querySelector("#reset");
reloadButton.addEventListener("click", () => document.location.reload());

Next we show how to set and reset a boolean attribute. When the toggle button is clicked we check if the boolean disabled property is defined (this property reflects the disabled attribute, and is true if the button is disabled and false otherwise). If the button is disabled we call Element.removeAttribute() to remove the attribute, which in turn enables the button. If the button is enabled, we disable the button by setting the disabled attribute to "disabled".

const toggleDisabledButton = document.querySelector("#toggle_disabled");

toggleDisabledButton.addEventListener("click", () => {
  if (helloButton.disabled) {
    // Button is disabled. Enable by removing attribute
    helloButton.removeAttribute("disabled");
  } else {
    // Button enabled. Disable by setting value to anything
    // (normally "" or "disabled")
    helloButton.setAttribute("disabled", "disabled");
  }
});

Results

The running example is shown below. You can see that the bottom button text is "helloButton", as we've set the name property and then it used it to set the button text. You can press the "Toggle" button to disable and enable the "helloButton".

Setting unsafe attributes

In this example we'll show how you might mitigate the risks of calling setAttributes() to set the srcdoc attribute on an <iframe>. This attribute sets the source HTML of a frame, and can hence inject potentially untrusted or unsafe code into the DOM.

The approach would be similar for setting src on HTML script elements, href on SVG script elements, and the onXxxx event handler attributes: the main difference is that you pass them different trusted type objects.

Trusted types are not yet supported on all browsers, so first we define the trusted types tinyfill. This acts as a transparent replacement for the Trusted Types JavaScript API:

if (typeof trustedTypes === "undefined")
  trustedTypes = { createPolicy: (n, rules) => rules };

Next we create a TrustedTypePolicy that defines a createHTML() for transforming an input string into TrustedHTML instances. Commonly, implementations of createHTML() use a library such as DOMPurify to sanitize the input, as shown below:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

Then we use this policy object to create a TrustedHTML object from the potentially unsafe input string, and assign the result to the element:

// The potentially malicious string
const untrustedString = "<p>I might be XSS</p><img src='x' onerror='alert(1)'>";

// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);

// Inject the TrustedHTML (which contains a trusted string)
const iframeElement = document.querySelector("#an_iframe");
iframeElement.setAttribute("srcdoc", trustedHTML);

Specifications

Browser compatibility

See also

• Element.hasAttribute()
• Element.getAttribute()
• Element.removeAttribute()
• Element.toggleAttribute()