CSSStyleSheet: insertRule() method
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.
The CSSStyleSheet.insertRule()
method inserts a new CSS rule into the current style sheet.
Note:
Although insertRule()
is exclusively a method of
CSSStyleSheet
, it actually inserts the rule into
CSSStyleSheet.cssRules
— its internal
CSSRuleList
.
Syntax
insertRule(rule)
insertRule(rule, index)
Parameters
rule
-
A string containing the rule to be inserted. What the inserted rule must contain depends on its type:
index
Optional-
A positive integer less than or equal to
stylesheet.cssRules.length
, representing the newly inserted rule's position inCSSStyleSheet.cssRules
. The default is0
. (In older implementations, this was required. See Browser compatibility for details.)
Return value
The newly inserted rule's index within the stylesheet's rule-list.
Exceptions
IndexSizeError
DOMException
-
Thrown if
index
>CSSRuleList.length
. HierarchyRequestError
DOMException
-
Thrown if
rule
cannot be inserted atindex
0
due to some CSS constraint. SyntaxError
DOMException
-
Thrown if more than one rule is given in the
rule
parameter. HierarchyRequestError
DOMException
-
Thrown if trying to insert an
@import
at-rule after a style rule. InvalidStateError
DOMException
-
Thrown if
rule
is@namespace
and the rule-list has more than just@import
at-rules and/or@namespace
at-rules.
Examples
Inserting a new rule
This snippet pushes a new rule onto the top of my stylesheet.
myStyle.insertRule("#blanc { color: white }", 0);
Function to add a stylesheet rule
/**
* Add a stylesheet rule to the document (it may be better practice
* to dynamically change classes, so style information can be kept in
* genuine stylesheets and avoid adding extra elements to the DOM).
* Note that an array is needed for declarations and rules since ECMAScript does
* not guarantee a predictable object iteration order, and since CSS is
* order-dependent.
* @param {Array} rules Accepts an array of JSON-encoded declarations
* @example
addStylesheetRules([
['h2', // Also accepts a second argument as an array of arrays instead
['color', 'red'],
['background-color', 'green', true] // 'true' for !important rules
],
['.myClass',
['background-color', 'yellow']
]
]);
*/
function addStylesheetRules(rules) {
const styleEl = document.createElement("style");
// Append <style> element to <head>
document.head.appendChild(styleEl);
// Grab style element's sheet
const styleSheet = styleEl.sheet;
for (let i = 0; i < rules.length; i++) {
let j = 1,
rule = rules[i],
selector = rule[0],
propStr = "";
// If the second argument of a rule is an array of arrays, correct our variables.
if (Array.isArray(rule[1][0])) {
rule = rule[1];
j = 0;
}
for (let pl = rule.length; j < pl; j++) {
const prop = rule[j];
propStr += `${prop[0]}: ${prop[1]}${prop[2] ? " !important" : ""};\n`;
}
// Insert CSS Rule
styleSheet.insertRule(
`${selector}{${propStr}}`,
styleSheet.cssRules.length,
);
}
}
Specifications
Specification |
---|
CSS Object Model (CSSOM) # dom-cssstylesheet-insertrule |
Browser compatibility
BCD tables only load in the browser