PostCSS is a tool for transforming CSS with JS plugins. These plugins can support variables and mixins, transpile future CSS syntax, inline images, and more.
Google, Twitter, Alibaba, and Shopify uses PostCSS. Its plugin, Autoprefixer, is one of the most popular CSS processors.
PostCSS can do the same work as preprocessors like Sass, Less, and Stylus. But PostCSS is modular, 3-30 times faster, and much more powerful.
Twitter account: @postcss. Weibo account: postcss. VK.com page: postcss.
Examples | Features | Usage | Plugins | Write Own Plugin | Options |
---|
What is PostCSS
PostCSS itself is very small. It includes only a CSS parser, a CSS node tree API, a source map generator, and a node tree stringifier.
All CSS transformations are made by plugins. And these plugins are just small plain JS functions, which receive a CSS node tree, transform it, and return a modified tree.
You can use the cssnext plugin pack and write future CSS code right now:
:root {
--mainColor: #ffbbaaff;
}
@custom-media --mobile (width <= 640px);
@custom-selector --heading h1, h2, h3, h4, h5, h6;
.post-article --heading {
color: color( var(--mainColor) blackness(+20%) );
}
@media (--mobile) {
.post-article --heading {
margin-top: 0;
}
}
Or if you like the Sass syntax, you could combine
postcss-nested
and postcss-mixins
:
@define-mixin social-icon $network $color {
&.is-$network {
background: $color;
}
}
.social-icon {
@mixin social-icon twitter #55acee;
@mixin social-icon facebook #3b5998;
padding: 10px 5px;
@media (max-width: 640px) {
padding: 0;
}
}
Features
Preprocessors are template languages, where you mix styles with code (like PHP does with HTML). In contrast, in PostCSS you write a custom subset of CSS. All code can only be in JS plugins.
As a result, PostCSS offers three main benefits:
- Performance: PostCSS, written in JS, is 3 times faster than libsass, which is written in C++.
- Future CSS: PostCSS plugins can read and rebuild an entire document, meaning that they can provide new language features. For example, cssnext transpiles the latest W3C drafts to current CSS syntax.
- New abilities: PostCSS plugins can read and change every part of CSS.
It makes many new classes of tools possible. Autoprefixer,
rtlcss
,doiuse
orpostcss-colorblind
are good examples.
Usage
You just need to follow these two steps to use PostCSS:
- Add PostCSS to your build tool.
- Select plugins from the list below and add them to your PostCSS process.
There are plugins for Grunt, Gulp, webpack, Broccoli, Brunch and ENB.
gulp.task('css', function () {
var postcss = require('gulp-postcss');
return gulp.src('src/**/*.css')
.pipe( postcss([ require('cssnext')(), require('cssnano')() ]) )
.pipe( gulp.dest('build/') );
});
For other environments, you can use the CLI tool or the JS API:
var postcss = require('postcss');
postcss([ require('cssnext')(), require('cssnano')() ])
.process(css, { from: 'src/app.css', to: 'app.css' })
.then(function (result) {
fs.writeFileSync('app.css', result.css);
if ( result.map ) fs.writeFileSync('app.css.map', result.map);
});
Read the PostCSS API for more details about the JS API.
Plugins
Control
With postcss-plugin-context
you can run different plugins
on different parts of CSS.
.css-example.is-test-for-css4-browsers {
color: gray(255, 50%);
}
@context cssnext {
.css-example.is-fallback-for-all-browsers {
color: gray(255, 50%);
}
}
Packs
cssnano
contains plugins that optimize CSS size for use in production.cssnext
contains plugins that allow you to use future CSS features today.atcss
contains plugins that transform your CSS according to special annotation comments.
Future CSS Syntax
postcss-color-function
supports functions to transform colors.postcss-color-gray
supports thegray()
function.postcss-color-hex-alpha
supports#rrggbbaa
and#rgba
notation.postcss-color-hwb
transformshwb()
to widely compatiblergb()
.postcss-color-rebeccapurple
supports therebeccapurple
color.postcss-custom-media
supports custom aliases for media queries.postcss-custom-properties
supports variables, using syntax from the W3C Custom Properties.postcss-css-variables
supports variables for descendant/nested rules and at-rulespostcss-custom-selectors
adds custom aliases for selectors.postcss-font-variant
transpiles human-readablefont-variant
to more widely supported CSS.postcss-host
makes the Shadow DOM’s:host
selector work properly with pseudo-classes.postcss-media-minmax
adds<=
and=>
statements to media queries.postcss-selector-not
transforms CSS4:not()
to CSS3:not()
.mq4-hover-shim
supports the@media (hover)
feature.
See also cssnext
plugins pack to add Future CSS syntax by one line of code.
Fallbacks
postcss-color-rgba-fallback
transformsrgba()
to hexadecimal.postcss-epub
adds the-epub-
prefix to relevant properties.postcss-image-set
addsbackground-image
with first image forimage-set()
postcss-opacity
adds opacity filter for IE8.postcss-pseudoelements
Convert::
selectors into:
selectors for IE 8 compatibility.postcss-vmin
generatesvm
fallback forvmin
unit in IE9.postcss-will-change
inserts 3D hack beforewill-change
property.autoprefixer
adds vendor prefixes for you, using data from Can I Use.cssgrace
provides various helpers and transpiles CSS 3 for IE and other old browsers.pixrem
generates pixel fallbacks forrem
units.
Language Extensions
postcss-bem
adds at-rules for BEM and SUIT style classes.postcss-color-alpha
transforms#hex.a
,black(alpha)
andwhite(alpha)
torgba()
.postcss-color-hcl
transformshcl(H, C, L)
andHCL(H, C, L, α)
to#rgb
andrgba()
.postcss-each
adds@each
statement.postcss-for
adds@for
loops.postcss-color-scale
adds a color scalecs()
function.postcss-conditionals
adds@if
statements.postcss-mixins
enables mixins more powerful than Sass’s, defined within stylesheets or in JS.postcss-map
enables configuration maps.postcss-modular-scale
adds a modular scalems()
function.postcss-nested
unwraps nested rules.postcss-quantity-queries
enables quantity queries.postcss-simple-extend
supports extending of silent classes, like Sass’s@extend
.postcss-simple-vars
supports for Sass-style variables.postcss-vertical-rhythm
adds a vertical rhythm unit calculated from base font-size and line-height.csstyle
adds components workflow to your styles.
Grids
postcss-grid
adds a semantic grid system.postcss-neat
is a semantic and fluid grid framework.lost
feature-richcalc()
grid system by Jeet author.
Optimizations
postcss-assets
allows you to simplify URLs, insert image dimensions, and inline files.postcss-at2x
handles retina background images via use ofat-2x
keyword.postcss-calc
reducescalc()
to values (when expressions involve the same units).postcss-data-packer
moves embedded Base64 data to a separate file.postcss-import
inlines the stylesheets referred to by@import
rules.postcss-single-charset
ensures that there is one and only one@charset
rule at the top of file.postcss-sprites
generates CSS sprites from stylesheets.postcss-url
rebases or inlinesurl()
s.postcss-zindex
rebases positivez-index
values.csswring
is a CSS minifier.css-byebye
removes the CSS rules that you don’t want.css-mqpacker
joins matching CSS media queries into a single statement.webpcss
adds URLs for WebP images for browsers that support WebP.
See also plugins in modular minifier cssnano
.
Shortcuts
postcss-default-unit
adds default unit to numeric CSS properties.postcss-easings
replaces easing names from easings.net withcubic-bezier()
functions.postcss-focus
adds:focus
selector to every:hover
.postcss-generate-preset
allows quick generation of rules. Useful for creating repetitive utilities.postcss-property-lookup
allows referencing property values without a variable.postcss-size
adds asize
shortcut that sets width and height with one declaration.postcss-verthorz
adds vertical and horizontal spacing declarations.
Others
postcss-brand-colors
inserts company brand colors in thebrand-colors
module.postcss-class-prefix
adds a prefix/namespace to class selectors.postcss-color-palette
transforms CSS 2 color keywords to a custom palette.postcss-colorblind
transforms colors using filters to simulate colorblindness.postcss-fakeid
transforms#foo
IDs to attribute selectors[id="foo"]
.postcss-flexboxfixer
unprefixes-webkit-
only flexbox in legacy CSS.postcss-gradientfixer
unprefixes-webkit-
only gradients in legacy CSS.postcss-log-warnings
logs warnings messages from other plugins in the console.postcss-messages
displays warning messages from other plugins right in your browser.postcss-pxtorem
converts pixel units torem
.postcss-style-guide
generates a style guide automatically.rtlcss
mirrors styles for right-to-left locales.
Analysis
postcss-bem-linter
lints CSS for conformance to SUIT CSS methodology.postcss-cssstats
returns an object with CSS statistics.css2modernizr
creates a Modernizr config file that requires only the tests that your CSS uses.doiuse
lints CSS for browser support, using data from Can I Use.list-selectors
lists and categorizes the selectors used in your CSS, for code review.
Fun
postcss-australian-stylesheets
Australian Style Sheets.postcss-canadian-stylesheets
Canadian Style Sheets.postcss-spiffing
lets you use British English in your CSS.
How to Develop PostCSS Plugin
Options
Source Map
PostCSS has great source maps support. It can read and interpret maps from previous transformation steps, autodetect the format that you expect, and output both external and inline maps.
To ensure that you generate an accurate source map, you must indicate the input
and output CSS files paths — using the options from
and to
, respectively.
To generate a new source map with the default options, simply set map: true
.
This will generate an inline source map that contains the source content.
If you don’t want the map inlined, you can use set map.inline: false
.
processor
.process(css, {
from: 'app.sass.css',
to: 'app.css',
map: { inline: false },
})
.then(function (result) {
result.map //=> '{ "version":3,
// "file":"app.css",
// "sources":["app.sass"],
// "mappings":"AAAA,KAAI" }'
});
If PostCSS finds source maps from a previous transformation, it will automatically update that source map with the same options.
If you want more control over source map generation, you can define the map
option as an object with the following parameters:
-
inline
boolean: indicates that the source map should be embedded in the output CSS as a Base64-encoded comment. By default, it istrue
. But if all previous maps are external, not inline, PostCSS will not embed the map even if you do not set this option.If you have an inline source map, the
result.map
property will be empty, as the source map will be contained within the text ofresult.css
. -
prev
string, object or boolean: source map content from a previous processing step (for example, Sass compilation). PostCSS will try to read the previous source map automatically (based on comments within the source CSS), but you can use this option to identify it manually. If desired, you can omit the previous map withprev: false
. -
sourcesContent
boolean: indicates that PostCSS should set the origin content (for example, Sass source) of the source map. By default, it’strue
. But if all previous maps do not contain sources content, PostCSS will also leave it out even if you do not set this option. -
annotation
boolean or string: indicates that PostCSS should add annotation comments to the CSS. By default, PostCSS will always add a comment with a path to the source map. But if the input CSS does not have any annotation comment, PostCSS will omit it, too, even if you do not set this option.By default, PostCSS presumes that you want to save the source map as
opts.to + '.map'
and will use this path in the annotation comment. But you can set another path by providing a string value forannotation
.If you have set
inline: true
, annotation cannot be disabled.
Safe Mode
If you provide a safe: true
option to the process
or parse
methods,
PostCSS will try to correct any syntax errors that it finds in the CSS.
postcss.parse('a {'); // will throw "Unclosed block"
postcss.parse('a {', { safe: true }); // will return CSS root for a {}
This is useful for legacy code filled with hacks. Another use-case is interactive tools with live input — for example, the Autoprefixer demo.