Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/postcss/postcss-simple-vars
PostCSS plugin for Sass-like variables
https://github.com/postcss/postcss-simple-vars
Last synced: about 1 month ago
JSON representation
PostCSS plugin for Sass-like variables
- Host: GitHub
- URL: https://github.com/postcss/postcss-simple-vars
- Owner: postcss
- License: mit
- Created: 2015-01-31T13:55:45.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2023-10-08T00:24:38.000Z (about 1 year ago)
- Last Synced: 2024-04-14T02:32:52.979Z (7 months ago)
- Language: JavaScript
- Homepage:
- Size: 1.24 MB
- Stars: 411
- Watchers: 9
- Forks: 41
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# PostCSS Simple Variables
[PostCSS] plugin for Sass-like variables.
You can use variables inside values, selectors and at-rule parameters.
```pcss
$dir: top;
$blue: #056ef0;
$column: 200px;
.menu_link {
background: $blue;
width: $column;
}
.menu {
width: calc(4 * $column);
margin-$(dir): 10px;
}
```
```css
.menu_link {
background: #056ef0;
width: 200px;
}
.menu {
width: calc(4 * 200px);
margin-top: 10px;
}
```
If you want be closer to W3C spec,
you should use [postcss-custom-properties] and [postcss-at-rules-variables] plugins.
Look at [postcss-map] for big complicated configs.
[postcss-at-rules-variables]: https://github.com/GitScrum/postcss-at-rules-variables
[postcss-custom-properties]: https://github.com/postcss/postcss-custom-properties
[postcss-map]: https://github.com/pascalduez/postcss-map
[PostCSS]: https://github.com/postcss/postcss
## Interpolation
There is special syntax for using variables inside CSS words:
```pcss
$prefix: my-company-widget
$prefix { }
$(prefix)_button { }
```
## Comments
You can use variables in comments too (for example, to generate special
[mdcss] comments). Syntax for comment variables is different to separate
them from PreCSS code examples:
```pcss
$width: 100px;
/* $width: <<$(width)>> */
```
compiles to:
```css
/* $width: 100px */
```
[mdcss]: https://github.com/jonathantneal/mdcss
## Escaping
If you want to escape `$` in the `content` property, use Unicode escape syntax.
```css
.foo::before {
content: "\0024x";
}
```
If you want to use e.g. `:` in a selector variable, use the corresponding unicode escape sequence:
```css
/* Given */
$selector: .my-component[data-emoji="\U0001f389"]\u003Adisabled;
$selector {
width: 1px;
}
/* Generates */
.my-component[data-emoji="🎉"]:disabled {
width: 1px;
}
```
Note: Use `\u` for 4-digit sequences and `\U` for 8-digit sequences.
## Usage
**Step 1:** Install plugin:
```sh
npm install --save-dev postcss postcss-simple-vars
```
**Step 2:** Check your project for existing PostCSS config: `postcss.config.js`
in the project root, `"postcss"` section in `package.json`
or `postcss` in bundle config.
If you do not use PostCSS, add it according to [official docs]
and set this plugin in settings.
**Step 3:** Add the plugin to plugins list:
```diff
module.exports = {
plugins: [
+ require('postcss-simple-vars'),
require('autoprefixer')
]
}
```
[official docs]: https://github.com/postcss/postcss#usage
## Options
Call plugin function to set options:
```js
require('postcss-simple-vars')({ silent: true })
```
### `variables`
Set default variables. It is useful to store colors or other constants
in a common file:
```js
// config/colors.js
module.exports = {
blue: '#056ef0'
}
// postcss.config.js
const colors = require('./config/colors')
const vars = require('postcss-simple-vars')
module.exports = {
plugins: [
require('postcss-simple-vars')({ variables: colors })
]
}
```
You can use a function return an object, if you want to update default
variables in webpack hot reload:
```js
require('postcss-simple-vars')({
variables: function () {
return require('./config/colors');
}
})
```
### `onVariables`
Callback invoked once all variables in css are known. The callback receives
an object representing the known variables, including those explicitly declared
by the [`variables`](#variables) option.
```js
require('postcss-simple-vars')({
onVariables (variables) {
console.log('CSS Variables');
console.log(JSON.stringify(variables, null, 2));
}
})
```
### `unknown`
Callback on unknown variable name. It receives the node instance, variable name
and PostCSS Result object.
```js
require('postcss-simple-vars')({
unknown (node, name, result) {
node.warn(result, 'Unknown variable ' + name);
}
})
])
```
### `silent`
Leave unknown variables in CSS and do not throw an error. Default is `false`.
### `only`
Set value only for variables from this object.
Other variables will not be changed. It is useful for PostCSS plugin developers.
### `keep`
Keep variables as is and not delete them. Default is `false`.
## Messages
This plugin passes `result.messages` for each variable:
```js
const result = await postcss([vars]).process('$one: 1; $two: 2')
console.log(result.messages)
```
will output:
```js
[
{
plugin: 'postcss-simple-vars',
type: 'variable',
name: 'one'
value: '1'
},
{
plugin: 'postcss-simple-vars',
type: 'variable',
name: 'two'
value: '2'
}
]
```
You can access this in `result.messages` and
in any plugin that included after `postcss-simple-vars`.