postcss-modules-values

What is postcss-modules-values?

The postcss-modules-values package is a PostCSS plugin that allows you to define and use custom values (variables) within your CSS modules. This can help you manage and reuse values like colors, sizes, and other design tokens across your stylesheets.

What are postcss-modules-values's main functionalities?

Define Custom Values

This feature allows you to define custom values in one CSS file and import them into another. This helps in maintaining consistency and reusability of design tokens across different stylesheets.

/* variables.css */
@value primaryColor: #3498db;
@value padding: 10px;

/* styles.css */
@value primaryColor, padding from './variables.css';

.button {
  background-color: primaryColor;
  padding: padding;
}

Scoped Values

Scoped values allow you to import and use values in a specific scope, ensuring that the values are only available where they are needed. This helps in avoiding global namespace pollution.

/* variables.css */
@value primaryColor: #3498db;

/* component.css */
@value primaryColor from './variables.css';

.header {
  color: primaryColor;
}

Nested Values

Nested values allow you to group related values together, making it easier to manage and use them in a structured way. This is particularly useful for organizing design tokens.

/* variables.css */
@value colors: {
  primary: #3498db,
  secondary: #2ecc71
};

/* styles.css */
@value colors from './variables.css';

.button {
  background-color: colors.primary;
}

Other packages similar to postcss-modules-values

postcss-simple-vars

postcss-simple-vars is a PostCSS plugin that allows you to use Sass-like variables in your CSS. It provides a simpler syntax for defining and using variables, but lacks the scoping and nesting capabilities of postcss-modules-values.

postcss-custom-properties

postcss-custom-properties is a PostCSS plugin that transforms W3C CSS Custom Properties (CSS variables) syntax into a static representation. It is more aligned with the native CSS variables specification and provides broader browser compatibility, but does not offer the same level of modularity as postcss-modules-values.

postcss-advanced-variables

postcss-advanced-variables is a PostCSS plugin that extends the capabilities of CSS variables with features like conditionals, loops, and functions. It offers more advanced features compared to postcss-modules-values, but may be overkill for simpler use cases.

README

CSS Modules: Values

Pass arbitrary values between your module files

Usage

/* colors.css */
@value primary: #BF4040;
@value secondary: #1F4F7F;

.text-primary {
  color: primary;
}

.text-secondary {
  color: secondary;
}

/* breakpoints.css */
@value small: (max-width: 599px);
@value medium: (min-width: 600px) and (max-width: 959px);
@value large: (min-width: 960px);

/* my-component.css */
/* alias paths for other values or composition */
@value colors: "./colors.css";
/* import multiple from a single file */
@value primary, secondary from colors;
/* make local aliases to imported values */
@value small as bp-small, large as bp-large from "./breakpoints.css";
/* value as selector name */
@value selectorValue: secondary-color;

.selectorValue {
  color: secondary;
}

.header {
  composes: text-primary from colors;
  box-shadow: 0 0 10px secondary;
}

@media bp-small {
  .header {
    box-shadow: 0 0 4px secondary;
  }
}
@media bp-large {
  .header {
    box-shadow: 0 0 20px secondary;
  }
}

If you are using Sass along with this PostCSS plugin, do not use the colon : in your @value definitions. It will cause Sass to crash.

Note also you can import multiple values at once but can only define one value per line.

@value a: b, c: d; /* defines a as "b, c: d" */

Justification

See this PR for more background

License

ISC

With thanks

• Mark Dalgleish
• Tobias Koppers
• Josh Johnston

---

Glen Maddern, 2015.

Changelog

4.0.0-rc.0 - 2020-09-18

BREAKING CHANGE

• minimum supported Node.js version is >= 10.13.0 || >= 12.13.0 || >= 14
• minimum supported postcss version is ^8.0.3
• postcss was moved to peerDependencies, you need to install postcss in your project before use the plugin