CSSStyleSheet.insertRule()
CSSStyleSheet.insertRule() method inserts a new CSS rule into the current style sheet. (with some restrictions)
More specifically, though insertRule() is exclusively a method of the CSSStyleSheet
, it actually inserts the rule into the CSSRuleList
therein.
What the rule must contain depends on its type: For rule-sets the rule specifies both the selector and the style declaration. For at-rules, the rule specifies both the at-identifier and the rule content.
Syntax
<var>stylesheet</var>.insertRule(<var>rule</var>, <var>index</var>)
Parameters
rule
is aDOMString
containing the rule to be inserted,
...where rule specifies selector and declaration, or at-identifier and rule content.index
is anunsigned int
representing the position of an stylesheet.cssRules to insert at,
...where index-0 is first rule, and index-max is just after last rule and is the same as length of the stylesheet.cssRules in spreadsheet,.
Note: index is now formally required, and omitting it may cause a warning or error. For example:
- Chrome: " [Warning-icon] Calling CSSStyleSheet.insertRule() with one argument is deprecated. Please pass the index argument as well"
Return value
The index within the style sheet's rule-list of the newly inserted rule.
Restrictions
CSS stylesheet rule-lists have a number of intuitive and not-so-intuitive restrictions affecting how and where rules can be inserted. Violating these will likely cause an error raised as a DOMException
- If index > number of rules in the stylesheet (the
CSSRuleList
.length), then aborts with IndexSizeError. - If rule cannot be inserted at index 0 due to some CSS constraint, then aborts with HierarchyRequestError.
- If more than one rule is given in the rule parameter, then aborts with SyntaxError
- If trying to insert an @import at-rule after a style rule, then aborts with HierarchyRequestError.
- If rule is @namespace at-rule and list has more than just @import at-rules and/or @namespace at-rules, then aborts with InvalidStateError.
Examples
Example 1
// push a new rule onto the top of my stylesheet myStyle.insertRule("#blanc { color: white }", 0);
Example 2
/** * Add a stylesheet rule to the document (may be better practice, however, * 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 afford a predictable object iteration order and since CSS is * order-dependent (i.e., it is cascading); those without need of * cascading rules could build a more accessor-friendly object-based API. * @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) { var styleEl = document.createElement('style'), styleSheet; // Append style element to head document.head.appendChild(styleEl); // Grab style sheet styleSheet = styleEl.sheet; for (var i = 0, rl = rules.length; i < rl; i++) { var j = 1, rule = rules[i], selector = rules[i][0], propStr = ''; // If the second argument of a rule is an array of arrays, correct our variables. if (Object.prototype.toString.call(rule[1][0]) === '[object Array]') { rule = rule[1]; j = 0; } for (var pl = rule.length; j < pl; j++) { var prop = rule[j]; propStr += prop[0] + ':' + prop[1] + (prop[2] ? ' !important' : '') + ';\n'; } // Insert CSS Rule styleSheet.insertRule(selector + '{' + propStr + '}', styleSheet.cssRules.length); } }
Specifications
Specification | Status | Comment |
---|---|---|
CSS Object Model (CSSOM) The definition of 'CSSStyleSheet.insertRule' in that specification. |
Working Draft | No change from Document Object Model (DOM) Level 2 Style Specification. |
Document Object Model (DOM) Level 2 Style Specification The definition of 'CSSStyleSheet.insertRule' in that specification. |
Recommendation | Initial definition |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | 9 | (Yes) | (Yes) |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
Legacy browser support
-
Internet Explorer - pre v9
addRule(selector, rule [, index]); -- Example:addRule('pre', 'font: 14px verdana'); // add rule at end
Also note the non-standardremoveRule()
and.rules
instead ofdeleteRule()
and.cssRules
respectively.
See also
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/cssstylesheet/insertrule