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 CSSStyleSheet.cssRules, 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

stylesheet.insertRule(rule[, index])

Parameters

rule

A DOMString containing the rule to be inserted, where rule specifies selector and declaration, or at-identifier and rule content.

index Optional

An unsigned integer not greater than stylesheet.cssRules.length representing the position in CSSStyleSheet.cssRules to insert at. In older implementations, this was required. See Browser compatibility for details. The default is 0.

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

Browser compatibility

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-standard removeRule()  and .rules  instead of deleteRule() and .cssRules respectively.

See also

• CSSStyleSheet.deleteRule
• Cross-Browser CSS-rules ordering (CSS1)
• Quirksmode - CSS