postcss-mixins

What is postcss-mixins?

The postcss-mixins package allows you to define and use mixins in your CSS, which can help you avoid code repetition and make your stylesheets more maintainable. Mixins are reusable chunks of code that you can include in other rulesets.

What are postcss-mixins's main functionalities?

Defining and Using Mixins

You can define a mixin using the @mixin directive and then include it in other rulesets using the @include directive. This helps in reusing common styles across different selectors.

/* Define a mixin */
@mixin border-radius($radius) {
  border-radius: $radius;
}

/* Use the mixin */
.button {
  @include border-radius(5px);
}

Parameterizing Mixins

Mixins can accept parameters, allowing you to customize the output of the mixin for different use cases. This makes your mixins more flexible and powerful.

/* Define a mixin with parameters */
@mixin box-shadow($x, $y, $blur, $color) {
  box-shadow: $x $y $blur $color;
}

/* Use the mixin with different parameters */
.card {
  @include box-shadow(2px, 2px, 5px, rgba(0, 0, 0, 0.3));
}

.modal {
  @include box-shadow(0, 4px, 10px, rgba(0, 0, 0, 0.5));
}

Conditional Logic in Mixins

You can include conditional logic within your mixins to handle different scenarios. This example shows how to create a responsive mixin that adjusts a property based on a breakpoint.

/* Define a mixin with conditional logic */
@mixin responsive($property, $value, $breakpoint) {
  #{$property}: $value;
  @media (min-width: $breakpoint) {
    #{$property}: calc($value * 1.5);
  }
}

/* Use the mixin */
.container {
  @include responsive(width, 100px, 768px);
}

Other packages similar to postcss-mixins

postcss-extend

The postcss-extend package allows you to extend existing rulesets with additional styles, similar to the @extend directive in Sass. Unlike postcss-mixins, which focuses on reusable chunks of code, postcss-extend is more about inheriting styles from other selectors.

postcss-nested

The postcss-nested package enables you to nest your CSS selectors in a way that follows the same visual hierarchy of your HTML. While postcss-mixins focuses on reusable code blocks, postcss-nested helps in organizing your CSS in a more readable and maintainable way.

postcss-simple-vars

The postcss-simple-vars package allows you to use variables in your CSS, similar to Sass variables. While postcss-mixins provides reusable code blocks, postcss-simple-vars focuses on simplifying the management of CSS values through variables.

README

PostCSS Mixins

PostCSS plugin for mixins.

Note, that you must set this plugin before postcss-simple-vars and postcss-nested.

@define-mixin icon $network, $color: blue {
    .icon.is-$(network) {
        color: $color;
        @mixin-content;
    }
    .icon.is-$(network):hover {
        color: white;
        background: $color;
    }
}

@mixin icon twitter {
    background: url(twt.png);
}
@mixin icon youtube, red {
    background: url(youtube.png);
}

.icon.is-twitter {
    color: blue;
    background: url(twt.png);
}
.icon.is-twitter:hover {
    color: white;
    background: blue;
}
.icon.is-youtube {
    color: red;
    background: url(youtube.png);
}
.icon.is-youtube:hover {
    color: white;
    background: red;
}

See also postcss-define-property for some simple cases.

Usage

postcss([ require('postcss-mixins') ])

See PostCSS docs for examples for your environment.

Mixins

CSS Mixin

Simple template defined directly in CSS to prevent repeating yourself.

See postcss-simple-vars docs for arguments syntax.

You can use it with postcss-nested plugin:

@define-mixin icon $name {
    padding-left: 16px;
    &::after {
        content: "";
        background-url: url(/icons/$(name).png);
    }
}

.search {
    @mixin icon search;
}

Unlike Sass, PostCSS has no if or while statements. If you need some complicated logic, you should use function mixin.

Function Mixin

This type of mixin gives you full power of JavaScript. You can define this mixins in mixins option.

This type is ideal for CSS hacks or business logic.

Also you should use function mixin if you need to change property names in mixin, because postcss-simple-vars doesn’t support variables in properties yet.

First argument will be @mixin node, that called this mixin. You can insert your declarations or rule before or after this node. Other arguments will be taken from at-rule parameters.

See PostCSS API about nodes API.

require('postcss-mixins')({
    mixins: {
        icons: function (mixin, dir) {
            fs.readdirSync('/images/' + dir).forEach(function (file) {
                var icon = file.replace(/\.svg$/, '');
                var rule = postcss.rule('.icon.icon-' + icon);
                rule.append({
                    prop:  'background',
                    value: 'url(' + dir + '/' + file + ')'
                });
                mixin.replaceWith(rule);
            });
        }
    }
});

@mixin icons signin;

.icon.icon-back { background: url(signin/back.svg) }
.icon.icon-secret { background: url(signin/secret.svg) }

You can also return an object if you don’t want to create each node manually:

require('postcss-mixins')({
    mixins: {
        hidpi: function (path) {
            return {
                '&': {
                    background: 'url(' + path + ')'
                },
                '@media (min-resolution: 120dpi)': {
                    '&': {
                        background: 'url(' + path + '@2x)'
                    }
                }
            }
        }
    }
}

Or you can use object instead of function:

require('postcss-mixins')({
    mixins: {
        clearfix: {
            '&::after': {
                content: '""',
                display: 'table',
                clear: 'both'
            }
        }
    }
}

Options

Call plugin function to set options:

postcss([ require('postcss-mixins')({ mixins: { … } }) ])

mixins

Type: Object

Object of function mixins.

mixinsDir

Type: string|string[]

Autoload all mixins from one or more dirs. Mixin name will be taken from file name.

// gulpfile.js

require('postcss-mixins')({
    mixinsDir: path.join(__dirname, 'mixins')
})

// mixins/clearfix.js

module.exports = {
    '&::after': {
        content: '""',
        display: 'table',
        clear: 'both'
    }
}

mixinsFiles

Type: string|string[]

Similar to mixinsDir; except, you can provide glob syntax to target or not target specific files.

require('postcss-mixins')({
    mixinsFiles: path.join(__dirname, 'mixins', '!(*.spec.js)')
})

silent

Remove unknown mixins and do not throw a error. Default is false.

Changelog

1.0.2

• Do not throw error on missed mixin dir (by Bogdan Chadkin).
• Use async plugin API (by Bogdan Chadkin).