PostCSS Local Keyframes

PostCSS plugin that makes @keyframes animations local by prefixing their names.

npm i postcss-local-keyframes

Example

Input

@keyframes local--loader {
  0% {
    transform: scale(0);
  }
  40% {
    transform: scale(1);
  }
}

.animation {
  animation: local--loader 1.2s 500ms infinite ease-in-out both;
}

.animation-2 {
  animation-name: local--loader;
}

Output

@keyframes _ihg3y_loader {
  0% {
    transform: scale(0);
  }
  40% {
    transform: scale(1);
  }
}

.animation {
  animation: _ihg3y_loader 1.2s 500ms infinite ease-in-out both;
}

.animation-2 {
  animation-name: _ihg3y_loader;
}

Usage

Add the plugin to your PostCSS configuration. If you are using autoprefixer, this plugin must be placed before it.

// postcss.config.js
module.exports = {
  plugins: [require("postcss-local-keyframes"), require("autoprefixer")],
};

You can also pass options to the plugin.

// postcss.config.js
module.exports = {
  plugins: [
    require("postcss-local-keyframes")({ prefix: "my-prefix-" }),
    require("autoprefixer"),
  ],
};

Once the plugin is set up, you can use the local-- prefix to make @keyframes animations local. Any other animations will be left untouched.

Important notes

Animation names must be made local everywhere for the plugin to work properly: both in the animation definition (e.g. @keyframes local--my-animation) and in usages (e.g. animation-name: local--my-animation;).

Local animations only work within the same CSS file. You can't use a local animation from a different file.

Options

defaultScope

"global" | "local" - default: "global"

The default scope for @keyframes animations. If set to "global", animations will be global by default. If set to "local", animations will be local by default.

In both cases, you can override specific animation scopes by using the local--<name> or global--<name> syntax (see below).

prefix

"<hash>" | string - default: "<hash>"

A fixed prefix that will be prepended to local @keyframes animation names. If omitted, a hashed prefix specific to each CSS file will be used.

generateHashedPrefix

(filename: string, css: string) => string - default: plugin.generateHashedPrefix

A function that generates a hashed prefix specific to each CSS file. The default implementation is declared in the index.js file (plugin.generateHashedPrefix), and it depends exclusively on the full content of the CSS file being processed.

If you want to re-use the built-in hash function (unsafe but simple and fast) in your custom hashed prefix generator, you can access it through the hash method in the plugin object:

const localKeyframesPlugin = require("postcss-local-keyframes");

module.exports = {
  plugins: [
    localKeyframesPlugin({
      generateHashedPrefix: (filename, css) =>
        `${localKeyframesPlugin.hash(css).slice(-5)}-custom-`,
    }),
    require("autoprefixer"),
  ],
};

globalRegExp

string - default: "^global--(.+)$"

A regular expression that matches global animation names. If an animation name matches this pattern, it will be considered global regardless of the defaultScope option. The pattern must contain a single capturing group that matches the animation name.

Do not pass a RegExp object directly to this option. Instead, pass a string that represents the pattern. The plugin will create a RegExp object from the string.

localRegExp

string - default: "^local--(.+)$"

A regular expression that matches local animation names. If an animation name matches this pattern, it will be considered local regardless of the defaultScope option. The pattern must contain a single capturing group that matches the animation name.

Do not pass a RegExp object directly to this option. Instead, pass a string that represents the pattern. The plugin will create a RegExp object from the string.

Global and local animations

By default, all animations are in the global scope, which means that they won't be prefixed and will be available globally with their original names. You can change the default by setting the defaultScope option to "local".

If you want a specific animation to be global or local regardless of the default setting, you can use the global--<name> or local--<name> naming pattern.

For example, if defaultScope is set to "local", you can make a specific animation global by using the global-- prefix:

@keyframes global--loader {
  0% {
    transform: scale(0);
  }
  40% {
    transform: scale(1);
  }
}

.animation {
  animation: global--loader 1.2s 500ms infinite ease-in-out both;
}

.animation-2 {
  animation-name: global--loader;
}

The output will be:

@keyframes loader {
  0% {
    transform: scale(0);
  }
  40% {
    transform: scale(1);
  }
}

.animation {
  animation: loader 1.2s 500ms infinite ease-in-out both;
}

.animation-2 {
  animation-name: loader;
}

Similarly, if defaultScope is set to "global", you can make a specific animation local by using the local-- prefix:

@keyframes local--loader {
  0% {
    transform: scale(0);
  }
  40% {
    transform: scale(1);
  }
}

.animation {
  animation: local--loader 1.2s 500ms infinite ease-in-out both;
}

.animation-2 {
  animation-name: local--loader;
}

The output will be:

@keyframes _ihg3y_loader {
  0% {
    transform: scale(0);
  }
  40% {
    transform: scale(1);
  }
}

.animation {
  animation: _ihg3y_loader 1.2s 500ms infinite ease-in-out both;
}

.animation-2 {
  animation-name: _ihg3y_loader;
}

The naming pattern for global and local animations can be customized with the globalRegExp and localRegExp options.

Acknowledgments

This plugin was forked from postcss-prefix-keyframe by VitaliyR.