Skip to main content

CSSRule

caution

CSSRulePlugin has been deprecated in favor of using CSS variables which have excellent browser support these days. GSAP has native support for animating CSS variables, like:

gsap.to("html", { "--my-variable": 100, duration: 2 });

CSS variables demo:

loading...

Allows GSAP to animate a raw style sheet rule which affects all objects of a particular selector rather than affecting an individual DOM element's inline styles.

For example, if you have a CSS class named myClass that sets background-color to #FF0000, you could tween that to a different color and all of the objects on the page that have a class of myClass would have their background color change. Typically it is best to use the regular CSSPlugin to animate CSS-related properties of individual elements so that you can get very precise control over each object, but sometimes it can be useful to animate the global rules themselves instead. For example, pseudo elements like ::after and ::before are impossible to reference directly in JavaScript, but you can animate them using CSSRulePlugin.

The plugin itself has a static getRule() method that you can use to grab a reference to the style sheet itself based on the CSS selector.

For example, let's say you have CSS like this:

.myClass {
    color: #FF0000;
}
.myClass::before {
    content: "This content is before.";
    color: #00FF00;
}

If you want to tween the color of the .myClass:before to blue. Make sure you load the CSSRulePlugin file and then do this:

var rule = CSSRulePlugin.getRule(".myClass::before"); //get the rule
gsap.to(rule, { duration: 3, cssRule: { color: "blue" } });

And if you want to get all of the ::before pseudo elements, the getRule() will return an array of them, so I could do this:

gsap.to( CSSRulePlugin.getRule("::before"), {duration: 3, cssRule: {color: "blue"}});>

Keep in mind that it is typically best to tween a property that has already been defined in the specific rule that you're selecting because it cannot perform a calculated style (the combination of styles from other selectors that might pertain to similar elements). For example, if we didn't define any color initially for the .myClass::before and tried to tween its color to blue, it would start from transparent and go to blue. One way around this is to simply set your starting values explicitly in the tween by doing a fromTo(). That way there's no having to guess what the starting value should be when it isn't defined previously.

Don't forget to wrap the values in a cssRule: {} object.

Styles defined inside media queries may not be accessible or tweenable.

Alternatively, convert your pseudo-elements to real HTML elements and animate them directly like you would any other DOM elements.

Methods​

CSSRulePlugin.getRule( selector:String ) : Object

[static] Provides a simple way to find the style sheet object associated with a particular selector like ".myClass" or "#myID".

FAQs​

How do I include CSSRulePlugin in my project?

See the installation page for all the options (CDN, NPM, download, etc.) where there's even an interactive helper that provides the necessary code. Easy peasy. Don't forget to register CSSRulePlugin like this in your project:

gsap.registerPlugin(CSSRulePlugin)

Is this included in the GSAP core?

No, you must load/import it separately

Is this only for Club GSAP members?

No, it's available to everyone for free! But Club GSAP is pretty awesome...just sayin'.

It works fine during development, but suddenly stops working in the production build! What do I do?

Your build tool is probably dropping the plugin when tree shaking and you forgot to register CSSRulePlugin (which protects it from tree shaking). Just register the plugin like this:

gsap.registerPlugin(CSSRulePlugin)

Is it bad to register a plugin multiple times?

No, it's perfectly fine. It doesn't help anything, nor does it hurt.

Contents