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:

1let util = require('postcss-plugin-utilities'),
2    width = '1600px',
3    height = util.calc('x/16*9', width); 
4    // 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:

1let util = require('postcss-plugin-utilities'),
2    selector = 'p, ul, ol',
3    newSelector = util.eachSelector(selector, '&:before');
4    // 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:

1let util = require('postcss-plugin-utilities'),
2    values = ['20px', 'center', 'black'],
3    theObject = util.filterObject(values, {
4        // rules are set up using an object, 
5        // the values being an array of correct values 
6        // or a validation function
7        align: ['left', 'right', 'center'], // left, right or center are accepted values
8        blackOrWhite: [(testingValue) => { // a function can be passedin to validate
9            if(['black', 'white'].indexOf(testingValue) >= 0) { return true; }
10            return false;
11        }],
12        size: [util.isSize], // we can also link in functions for validation
13        shadow: [util.isBoxShadow]
14    }, {
15        // a set of defaults can be passed in as well
16        size: '30px',
17        shadow: '1px 1px 1px black'
18    });
19    // theObject will result in
20    // {
21    //     align: 'center',
22    //     blackOrWhite: 'black',
23    //     size: '20px',
24    //     shadow: '1px 1px 1px black'
25    // }

getRGB(color)

Get an object of RGB and possibly A values from a color string

getSides(values, rules)

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

Example:

1let util = require('postcss-plugin-utilities'),
2    values = ['20px', '10px'],
3    sides = util.getSides(values, {
4        'border-top': [util.isSize],
5        'border-right': [util.isSize],
6        'border-bottom': [util.isSize],
7        'border-left': [util.isSize]
8    });
9    // sides will equal to
10    // {
11    //     'border-top': '20px',
12    //     'border-right': '10px',
13    //     'border-bottom': '20px',
14    //     'border-left': '10px',
15    // }

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)

isTransition(value)

Check if a string is a transition value

isURL(value)

Return true if a value is a valid CSS URL

nameToHex(colorName)

Convert a named color to its hex value

overwrite(valuesObj, defaultObj)

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

removeNode(node)

Recursively delete nodes

rgbToHex(rgbValue)

Convert an RGB value to its hex value

sassFunction(nodes, funcName, func)

Parse a SASS function and call a JS function on it

sassGetVar(variable, node)

Get the value of a sass variable

sassHasVar(variable, node)

Check if sass variable exists