CSSStyleDeclaration: setProperty() method
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
The
CSSStyleDeclaration.setProperty() method interface sets
a new value for a property on a CSS style declaration object.
Syntax
setProperty(propertyName, value)
setProperty(propertyName, value, priority)
Parameters
propertyName-
A string representing the CSS property name (hyphen case) to be modified.
valueOptional-
A string containing the new property value. If not specified, treated as the empty string. A
nullvalue is treated the same as the empty string ("").Note:
valuemust not contain"!important", that should be set using thepriorityparameter. priorityOptional-
A string allowing the CSS priority to be set to important. Only the values listed below are accepted:
"important"(case-insensitive) for setting the property as!important;"",undefined, ornullfor removing the!importantflag if present.
Anything else causes the method to return early and no change to happen (unless
valueis empty, in which case the property is removed regardless of thepriorityvalue).false, for example, is not a valid priority value.
Return value
None (undefined).
Exceptions
NoModificationAllowedErrorDOMException-
Thrown if the property or declaration block is read only.
Alternative usage
If priority can be omitted, JavaScript has a special simpler
syntax for setting a CSS property on a style declaration object:
style.cssPropertyName = "value";
Examples
Setting the box properties
In this example we have three buttons, which can be pressed to dynamically alter our box paragraph's border, background color, and text color to random values (see the live example at the end of this section).
The MDN live sample infrastructure combines all the CSS blocks in the example into a single inline style with the id css-output, so we first use document.getElementById() to find that sheet.
We then loop through the different rules contained inside the stylesheet in the array found at stylesheet.cssRules.
For each rule we check whether its CSSStyleRule.selectorText is equal to the selector .box p, which is the one we want.
If so, we store a reference to this CSSStyleRule object in a variable.
We then use three functions to generate random values for the properties in question, and update the rule with these values.
In each case, this is done with the setProperty() method, for example boxParaRule.style.setProperty('border', newBorder);.
HTML
<div class="controls">
<button class="border">Border</button>
<button class="bgcolor">Background</button>
<button class="color">Text</button>
</div>
<div class="box">
<p>Box</p>
</div>
CSS
html {
background: orange;
font-family: sans-serif;
height: 100%;
}
body {
height: inherit;
width: 80%;
min-width: 500px;
max-width: 1000px;
margin: 0 auto;
}
.controls {
display: flex;
justify-content: space-around;
align-items: center;
}
div button {
flex: 1;
margin: 20px;
height: 30px;
line-height: 30px;
}
.box {
display: flex;
justify-content: center;
align-items: center;
height: calc(100% - 70px);
}
.box p {
width: 50%;
text-align: center;
font-weight: bold;
font-size: 40px;
height: 150px;
line-height: 150px;
background: red;
border: 5px solid purple;
color: white;
transition: all 1s;
}
JavaScript
const borderBtn = document.querySelector(".border");
const bgColorBtn = document.querySelector(".bgcolor");
const colorBtn = document.querySelector(".color");
const box = document.querySelector(".box");
function random(min, max) {
const num = Math.floor(Math.random() * (max - min)) + min;
return num;
}
function randomColor() {
return `rgb(${random(0, 255)} ${random(0, 255)} ${random(0, 255)})`;
}
// Find the inline stylesheet generated for MDN live samples
const stylesheet = document.getElementById("css-output").sheet;
const boxParaRule = [...stylesheet.cssRules].find(
(r) => r.selectorText === ".box p",
);
function setRandomBorder() {
const newBorder = `${random(1, 50)}px solid ${randomColor()}`;
boxParaRule.style.setProperty("border", newBorder);
}
function setRandomBgColor() {
const newBgColor = randomColor();
boxParaRule.style.setProperty("background-color", newBgColor);
}
function setRandomColor() {
const newColor = randomColor();
boxParaRule.style.setProperty("color", newColor);
}
borderBtn.addEventListener("click", setRandomBorder);
bgColorBtn.addEventListener("click", setRandomBgColor);
colorBtn.addEventListener("click", setRandomColor);
Result
Specifications
| Specification |
|---|
| CSS Object Model (CSSOM) # dom-cssstyledeclaration-setproperty |
Browser compatibility
| desktop | mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
setProperty
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support