PostCSS JS Mixins

PostCSS plugin for custom mixin syntax

/* before */
.block {
    column(spaced, 1, 2);
}
 
/* after */
.block {
    float: left;
    width: 50%;
    margin-left: 5%;
}
 
/* before */
.block {
    spacedBlock(width: 10px);
}
 
/* after */
.block {
    margin-bottom: 2rem;
    width: 10px;
    display: block;
}

Usage

const syntax = require('postcss-wee-syntax');
const mixins = require('postcss-js-mixins');
 
postcss([ mixins({ /* options */ }) ]).process(input, {
            syntax: syntax
        })
        .then(result => {
            // Do something with result
        });

See PostCSS docs for examples for your environment.

Options

mixins

Type: Object
Default: {}

Register mixins that you want to reference in your style sheets.

const decl = require('postcss-js-mixins/lib/declaration');
const { isEmpty } = require('postcss-js-mixins/lib/helpers');
 
require('postcss-js-mixins')({
    mixins: {
        /**
        * Example of creating a shorthand with default value
        */
        spaced(value = '20px') {
            return decl('margin-bottom', value);
        }
    }
});

units

Type: Object
Default: { default: 'rem', lineHeight: 'em' }

These units will be appended intelligently when number values are passed without a unit. For example, the font-size property will have the unit appended, but opacity will not.

Writing Mixins

Mixins are written solely in JavaScript. They can return a declaration, a rule, or an array of declarations/rules.

Declaration

Declarations take a CSS property and it's value as arguments.

const decl = require('postcss-js-mixins/lib/declaration');
 
// Create single declaration
decl(prop, value);

Rule

Rules take a selector and an array of Declaration objects.

const rule = require('postcss-js-mixins/lib/rule');
 
// Create single declaration
rule('.block:after', [
    decl(prop, value),
    decl(prop, value)
]);

Methods

createMany

Matches indexes from two arrays to produce declarations for each. This is used when order matters for your mixin arguments.

// Create multiple declarations
function position(...args) {
    return decl.createMany(['top', 'right', 'left', 'bottom'], args);
}

position(10%, 0, false, 0);

createManyFromObj

Takes an object with property: value pairs and an optional prefix to prepend to each property value.

// Create multiple declarations from an object
function padding(top = 0, right = 0, bottom = 0, left = 0) {
    return decl.createManyFromObj({
        top: top,
        right: right,
        bottom: bottom,
        left: left
    }, 'padding');
}

padding(top: '10px', left: '12px');
 
/* Output */
padding-top: 10px;
padding-right: 0;
padding-bottom: 0;
padding-left: 12px;

Helper Methods

Helper methods have been provided in order to make writing mixins easier.

const helpers = require('postcss-js-mixins/lib/helpers');
const { darken, lighten } = require('postcss-js-mixins/lib/colorHelpers');

List of Helper Methods

• darken
• lighten
• calcOpacity
• hexToRgba
• isColor
• isEmpty
• isNumber
• isObject
• isPercentage
• isProvided
• isString
• isUnit
• prefix
• setDefaultUnits
• toDashCase
• toDegrees
• type
• unit

Note: This plugin uses TinyColor which has a large number of other color helper methods that can easily be exposed if requested.