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
• clear-fix
• hd breakpoint
• hide-visually
• hr
• margin
• no-hover
• no-js
• padding
• position
• reset-list
• reset-text
• size
• min-size
• max-size
• sticky-footer
• text-hide
• text-stroke
• triangle
• truncate
• word-wrap

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:

Install postcss-cli and the plugin on your project directory:

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

Add a postcss script to your package.json:

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

After this, you can run npm run postcss and transform your input.css into output.css.

Use with styled-jsx

styled-jsx allows you to use full, scoped and component-friendly CSS in your JSX (rendered on the server or the client) and you can add @util rules with postcss-utilities.

npm install --save styled-jsx styled-jsx-plugin-postcss postcss-utilities

Add postcss config in your package.json:

"postcss": {
    "plugins": {
        "postcss-utilities": {}
    }
}

Add styled-jsx/babel to plugins in your babel configuration:

{
  "plugins": [
    "styled-jsx/babel"
  ]
}

Then write @util rules in your code:

export default () => (
  <div>
    <p>only this paragraph will get the style :)</p>

    <style jsx>{`
      p {
        color: red;
        @util center;
      }
    `}</style>
  </div>
)

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