postcss-utilities

PostCSS Utility Library

postcss-utilities is a PostCSS plugin that includes the most commonly used mixins, shortcuts and helpers. It's as easy as specifying @util utility-name in your stylesheet, and postcss-utilities will handle the rest for you.

Check out the documentation to get started using postcss-utilities

Try it in the browser!

Motivation

PostCSS has a lot of plugins and some of them use non-standard CSS properties to work as mixins or helpers. This is not a best way for a PostCSS plugin, because developers will not understand what is the source of this property.

"This plugin saves us from many tiny plugins with unknown properties" ‒@ai proposal postcss/issues/645

What is the difference between preprocessor’s mixins libraries?

There are lot of Sass Mixins Libraries (over 65!), but postcss-utilities makes the difference. All mixins and helpers are built with JavaScript and you can add to your workflow with ease, as simple as adding autoprefixer or many others useful PostCSS plugins.

You can forget about copy mixins from project to project and focus on write your project specific mixins and use this plugin for the most generic helpers.

• You don’t need the extra files in your css codebase for mixins.
• You don’t need mixins for vendor prefixing (use autoprefixer plugin)
• You can use postcss-utilities with LESS, SASS, vanilla CSS or whatever you choice.

List of current utilities

IMPORTANT: The list of utilities is open for suggestions.

• aspect-ratio
• border-color
• border-radius
• border-style
• border-width
• center
• center-block
• circle
• clearfix
• hd breakpoint
• hide-visually
• hr
• margin
• no-hover
• no-js
• padding
• position
• reset-list
• reset-text
• size
• sticky-footer
• text-hide
• text-stroke
• triangle
• truncate
• word-break

Examples

Input

.cfx {
    @util clearfix;
}

.rounded-top {
    @util border-top-radius(4px);
}

@util no-hover {
    .box {
        background-color: #666;
    }
}

Output

.cfx:after {
    content: '';
    display: block;
    clear: both;
}

.rounded-top {
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
}

.no-hover .box {
    background-color: #666;
}

Usage

Quick usage

Using PostCSS CLI you can do the following:

First, install postcss-cli and the plugin on your project folder:

$ npm install postcss-cli postcss-utilities --save-dev

And finally add this script to your package.json:

"scripts": {
    "postcss": "postcss input.css -u postcss-utilities -o output.css -w"
}

After this you can run npm run postcss and transform your input.css into output.css. Note that -w is for observe file system changes and recompile as source files change.

For tasks runners and others enviroments

postcss([ require('postcss-utilities')({ /* options*/ }) ])

See PostCSS docs for examples of your environment.

Options

noHoverSelector

Type: string
Default: .no-hover

To use with no-hover utility

noJsSelector

Type: string
Default: .no-js

To use with no-js utility

ie8

Type: boolean
Default: false

Set true to use clearfix method IE8 compatible

centerMethod

Type: string
Default: transform Values: ['transform'|'flexbox']

To use with center utility

textHideMethod

Type: string
Default: indent Values: ['indent'|'font']

To use with text-hide utility

Contributing

The list of utilities is open for suggestions.

• Do you think that we should include a new utility? Create an issue with you proposal.
• Found an issue? Report it!.
• Would you like to contribute with code or documentation? Send a pull request

Contributors

• Marcus Tisäter

Changelog

v0.7.0

• Fix Container#remove warning for clearfix utility
• Unify format of alert and error messages
• Add options to set the selectors for no-hover and no-js utilities
• Add options to use alternative techniques for text-hide and center utilities #10
• Add option ie8 to use compatible method for clearfix
• Add "Quick usage" and styled-jsx support on README.md