README.md 5.02 KB

PostCSS Normalize PostCSS

NPM Version Build Status Support Chat

PostCSS Normalize lets you use the parts of normalize.css or sanitize.css that you need from your browserslist.

@import "normalize.css";
@import "sanitize.css";

PostCSS Normalize uses a non-opinionated version of normalize.css, but an opinionated version may also be used.

@import "normalize.css/opinionated.css";

Examples

Here is a sample of what normalize.css looks like when the browserslist is ie >= 9:

/**
 * Add the correct display in IE 9-.
 */

audio,
video {
  display: inline-block;
}

/**
 * Remove the border on images inside links in IE 10-.
 */

img {
  border-style: none;
}

And here is the same sample when the browserslist is ie >= 10:

/**
 * Remove the border on images inside links in IE 10-.
 */

img {
  border-style: none;
}

Usage

Add PostCSS Normalize to your project:

npm install postcss-normalize --save-dev

Add a browserslist entry in package.json:

{
  "browserslist": "last 2 versions"
}

Use PostCSS Normalize to process your CSS:

const postcssNormalize = require('postcss-normalize')

postcssNormalize.process(YOUR_CSS /*, processOptions, pluginOptions */)

Or use it as a PostCSS plugin:

const postcss = require('postcss')
const postcssNormalize = require('postcss-normalize')

postcss([
  postcssNormalize(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */)

PostCSS Normalize runs in all Node environments, with special instructions for:

Node PostCSS CLI Webpack Create React App Gulp Grunt

PostCSS Import Usage

PostCSS Normalize includes a postcssImport function to configure PostCSS Import and allow you to continue using the @import syntax.

const postcss = require('postcss')
const postcssImport = require('postcss-import')
const postcssNormalize = require('postcss-normalize')

postcss([
  postcssImport(
    postcssNormalize(
      /* pluginOptions (for PostCSS Normalize) */
    ).postcssImport(
      /* pluginOptions (for PostCSS Import) */
    )
  )
]) // now you can use @import "normalize.css", etc. again

Alternatively, use @import-normalize or @import-sanitize to avoid conflicts with @import transforms.

@import-normalize;
@import-normalize "opinionated.css";
@import-sanitize;

Options

allowDuplicates

The allowDuplicates option determines whether multiple, duplicate insertions of CSS libraries are allowed. By default, duplicate libraries are omitted.

postcssNormalize({ allowDuplicates: true })

forceImport

The forceImport option defines CSS libraries that will be inserted at the beginning of the CSS file. Unless overriden by allowDuplicates, duplicate CSS libraries would still be omitted.

postcssNormalize({ forceImport: true })

Specific CSS libraries may be defined.

postcssNormalize({
  forceImport: 'sanitize.css'
})

browsers

The browsers option defines an override of the project’s browserslist for PostCSS Normalize. This option should be avoided in leui of a browserslist file.

postcssNormalize({ browsers: 'last 2 versions' })

CSS Libraries

PostCSS Normalize can include normalize.css or sanitize.css and configure either with the following combinations:

@import "normalize"; /* also, @import "normalize.css" */
@import "normalize/opinionated"; /* also, @import "normalize.css/opinionated.css", @import "normalize.css/*" */
@import "sanitize"; /* also, @import "sanitize.css" */
@import "sanitize/forms"; /* also, @import "sanitize.css/forms.css" */
@import "sanitize/typography"; /* also, @import "sanitize.css/typography.css" */
@import "sanitize/page"; /* also, @import "sanitize.css/page.css" */
@import "sanitize/*"; /* also, @import "sanitize.css/*" (sanitize + all additions) */