PostCSS plugin to enable versatile theming.
Last updated 5 years ago by andywer .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install postcss-theme 
SYNC missed versions from official npm registry.

postcss-theme - Proper theming for PostCSS

Build Status NPM Version

Super lightweight, straight-forward and written with performance in mind. Can be used with Webpack, JSPM/System.js or anywhere else where you use PostCSS!

What is it able to do?

You have a user interface and a bunch of CSS files / fancy CSS modules to style it. You want to be able to customize this styling. Let's say you have this CSS file:

/* header.css */

@value black, white from '../theme/colors.css';

.header {
  composes: menu from '../theme/menu.css';
  background: black;
  color: white;

/* ../theme/colors.css */

@value black: #303030;
@value white: #F8F8F8;

/* ../theme/components/menu.css */

.menu {
  box-shadow: 2px 2px 5px;

We are using the postcss-modules-values plugin here, so we can declare variables and import variables from other files using @value. And we use postcss-modules-extract-imports so we can merge classes from different files into the current class using composes: some-other-class from './other-file.css'.

But you want to be able to change the styling! You could just overwrite all these style rules with your own ones, but that is a lot of work and you must adapt it everytime these rules change.

So we use postcss-theme and do this:

/* header.css */

/* `theme(colors)` will be re-written to `"./path/to/theme/colors.css"` */
@value black, white from theme(colors);

.header {
  /* will be resolved to the file path, too */
  composes: menu from theme(components/menu);
  background: black;
  color: white;

When configuring the PostCSS plugins in your webpack config or JSPM CSS loader:

import themePlugin from 'postcss-theme'

/* postcss plugins: */
  themePlugin({ themePath: './path/to/theme-folder' }),
  /* all other plugins go here */

Ta-da! You are now able to specify the path to the directory containing your theme's CSS files during your build process. Just change it to a directory containing another theme if you want to change the styling.


npm install postcss-theme --save


Just add this plugin to your array of PostCSS plugins and pass it an options object like { themePath: './path/to/theme-folder' }.


In your webpack config:

import theme from 'postcss-theme'

module.exports = {
  module: {
    loaders: [
        test:   /\.css$/,
        loader: 'style-loader!css-loader!postcss-loader'
  postcss: function () {
    return [
      theme({ themePath: './path/to/theme' }),
      // all other postcss plugins go here

JSPM (jspm-loader-css)

In your css loader file (css.js):

import { CSSLoader, Plugins } from 'jspm-loader-css'
import theme from 'postcss-theme'

const { fetch, bundle } = new CSSLoader([
  theme({ themePath: './path/to/theme' }),
  // or any other postcss plugins
], __moduleName)

export { fetch, bundle }

Vanilla postcss call

import postcss from 'postcss'
import autoprefixer from 'autoprefixer'
import extractImports from 'postcss-modules-extract-imports'
// ...
import theme from 'postcss-theme'

    themePath: './path/to/theme'
  // or whatever plugins you would like to use
]).process(/* ... */)


Version 1.1.1

Pass css.source to custom file path resolvers.

Version 1.1.0

Allow passing a custom file path resolver function (options.themeFileResolver).

Version 1.0.1

Windows fix. See this issue.

Version 1.0.0

Initial release.


This plugin is released under the terms of the MIT license. See LICENSE for details.

Current Tags

  • 1.1.1                                ...           latest (5 years ago)

4 Versions

  • 1.1.1                                ...           5 years ago
  • 1.1.0                                ...           5 years ago
  • 1.0.1                                ...           5 years ago
  • 1.0.0                                ...           5 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (2)
Dev Dependencies (6)
Dependents (0)

Copyright 2014 - 2017 © |