A list of utilities for creating PostCSS plugins

Installation

npm install postcss-plugin-utilities

Utilities

calc(calculation, values, return_with_units = true)

Do calculations on css (uses mathjs)

Example:

let util = require('postcss-plugin-utilities'),
    width = '1600px',
    height = util.calc('x/16*9', width); 
    // height will be 900px

contrastColor(color)

Returns either black or white depending on contrasting a color. Useful for calculating overlay text color for an unknown background-color.

eachSelector(selector, update)

Updates a selector with SASS like syntax

Example:

let util = require('postcss-plugin-utilities'),
    selector = 'p, ul, ol',
    newSelector = util.eachSelector(selector, '&:before');
    // newSelector will be 'p:before, ul:before, ol:before'

filterObject(values, rules, defaults = null)

Go through an array and filter the values as per set rules and falling back to defaults.

Example:

let util = require('postcss-plugin-utilities'),
    values = ['20px', 'center', 'black'],
    theObject = util.filterObject(values, {
        // rules are set up using an object, 
        // the values being an array of correct values 
        // or a validation function
        align: ['left', 'right', 'center'], // left, right or center are accepted values
        blackOrWhite: [(testingValue) => { // a function can be passedin to validate
            if(['black', 'white'].indexOf(testingValue) >= 0) { return true; }
            return false;
        }],
        size: [util.isSize], // we can also link in functions for validation
        shadow: [util.isBoxShadow]
    }, {
        // a set of defaults can be passed in as well
        size: '30px',
        shadow: '1px 1px 1px black'
    });
    // theObject will result in
    // {
    //     align: 'center',
    //     blackOrWhite: 'black',
    //     size: '20px',
    //     shadow: '1px 1px 1px black'
    // }

getSides(values, rules)

Wrap filter object and return sides values the same way as margin and padding works in CSS

Example:

let util = require('postcss-plugin-utilities'),
    values = ['20px', '10px'],
    sides = util.getSides(values, {
        'border-top': [util.isSize],
        'border-right': [util.isSize],
        'border-bottom': [util.isSize],
        'border-left': [util.isSize]
    });
    // sides will equal to
    // {
    //     'border-top': '20px',
    //     'border-right': '10px',
    //     'border-bottom': '20px',
    //     'border-left': '10px',
    // }

hexToRGB(hexValue)

Convert a hex color to RGB

isBezier(value)

Returns true if a value is a valid bezier

isBorder(value)

Return true if a value is a valid border

isBoxShadow(value)

Return true if a value is a valid box-shadow

isColor(value)

Return true if a value is a valid color

isCursor(value)

Return true if a value is a valid cursor

isHTML(value)

Return true if a value is a valid HTML element

isNumber(value)

Return true if a value is a valid number (unitless)

isProperty(value)

Return true if a value is a valid CSS property

isRegex(value, regex)

Checks if a value matches a regex (uses exact-regex)

isSizeList(value)

Return true if a value is a valid CSS size list (eg.: padding, margin)

isSize(value)

Return true if a value is a valid CSS size

isStep(value)

Return true if a value is a valid CSS animation step

isTextShadow(value)

Return true if a value is a valid text-shadow

isTime(value)

Return true if a value is a valid time (eg.: 3s)

isURL(value)

Return true if a value is a valid CSS URL

nameToHex(colorName)

Convert a named color to its hex value

rgbToHex(rgbValue)

Convert an RGB value to its hex value

overwrite(valuesObj, defaultObj)

Merge two arrays with the same properties to be overwritten with values (uses overwrite-object)