https://github.com/daniguardiola/postcss-local-keyframes
PostCSS plugin that makes animations local.
https://github.com/daniguardiola/postcss-local-keyframes
animation css keyframes postcss postcss-plugin
Last synced: 4 days ago
JSON representation
PostCSS plugin that makes animations local.
- Host: GitHub
- URL: https://github.com/daniguardiola/postcss-local-keyframes
- Owner: DaniGuardiola
- License: mit
- Created: 2024-05-27T13:13:39.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-06-11T19:24:46.000Z (over 1 year ago)
- Last Synced: 2025-01-22T19:01:45.934Z (about 1 year ago)
- Topics: animation, css, keyframes, postcss, postcss-plugin
- Language: JavaScript
- Homepage:
- Size: 127 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# PostCSS Local Keyframes
[PostCSS](https://github.com/postcss/postcss) plugin that makes `@keyframes` animations local by prefixing their names.
```sh
npm i postcss-local-keyframes
```
## Example
### Input
```css
@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
```css
@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.
```js
// postcss.config.js
module.exports = {
plugins: [require("postcss-local-keyframes"), require("autoprefixer")],
};
```
You can also pass options to the plugin.
```js
// 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--` or `global--` syntax (see below).
### prefix
`"" | string` - default: `""`
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`](./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:
```js
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--` or `local--` naming pattern.
For example, if `defaultScope` is set to `"local"`, you can make a specific animation global by using the `global--` prefix:
```css
@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:
```css
@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:
```css
@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:
```css
@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](https://github.com/VitaliyR/postcss-prefix-keyframe) by [VitaliyR](https://github.com/VitaliyR).