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.

We’d love to hear your thoughts on the next set of proposals for the JavaScript language. You can find a description of the proposals here.

Please take two minutes to fill out our short survey.

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:

For rule-sets, both a selector and a style declaration.
For at-rules, both an at-identifier and the rule content.

index Optional

A positive integer less than or equal to stylesheet.cssRules.length, representing the newly inserted rule's position in CSSStyleSheet.cssRules. The default is 0. (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 at index 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