[![NPM version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coverage][coveralls-image]][coveralls-url]

critical

Critical extracts & inlines critical-path (above-the-fold) CSS from HTML

Install

npm i -D critical

Build plugins

grunt-critical
Gulp users should use Critical directly
For Webpack use html-critical-webpack-plugin

Demo projects

Usage

Include:

import {generate} from 'critical';

Full blown example with available options:

generate({
  // Inline the generated critical-path CSS
  // - true generates HTML
  // - false generates CSS
  inline: true,

  // Your base directory
  base: 'dist/',

  // HTML source
  html: '<html>...</html>',

  // HTML source file
  src: 'index.html',

  // Your CSS Files (optional)
  css: ['dist/styles/main.css'],

  // Viewport width
  width: 1300,

  // Viewport height
  height: 900,

  // Output results to file
  target: {
    css: 'critical.css',
    html: 'index-critical.html',
    uncritical: 'uncritical.css',
  },

  // Extract inlined styles from referenced stylesheets
  extract: true,

  // ignore CSS rules
  ignore: {
    atrule: ['@font-face'],
    rule: [/some-regexp/],
    decl: (node, value) => /big-image\.png/.test(value),
  },
});

Generate and inline critical-path CSS

Basic usage:

generate({
  inline: true,
  base: 'test/',
  src: 'index.html',
  target: 'index-critical.html',
  width: 1300,
  height: 900,
});

Generate critical-path CSS

Basic usage:

generate({
  base: 'test/',
  src: 'index.html',
  target: 'styles/main.css',
  width: 1300,
  height: 900,
});

Generate and minify critical-path CSS:

generate({
  base: 'test/',
  src: 'index.html',
  target: 'styles/styles.min.css',
  width: 1300,
  height: 900,
});

Generate, minify and inline critical-path CSS:

generate({
  inline: true,
  base: 'test/',
  src: 'index.html',
  target: {
    html: 'index-critical.html',
    css: 'critical.css',
  },
  width: 1300,
  height: 900,
});

Generate and return output via callback:

generate({
    base: 'test/',
    src: 'index.html',
    width: 1300,
    height: 900,
    inline: true
}, (err, {css, html, uncritical}) => {
    // You now have critical-path CSS as well as the modified HTML.
    // Works with and without target specified.
    ...
});

Generate and return output via promise:

generate({
    base: 'test/',
    src: 'index.html',
    width: 1300,
    height: 900
}).then(({ css, html, uncritical }) => {
    // You now have critical-path CSS as well as the modified HTML.
    // Works with and without target specified.
}).catch(err => {
    // …
});

Generate and return output via async function:

const {css, html, uncritical} = await generate({
  base: 'test/',
  src: 'index.html',
  width: 1300,
  height: 900,
});

Generate critical-path CSS with multiple resolutions

When your site is adaptive and you want to deliver critical CSS for multiple screen resolutions this is a useful option. note: (your final output will be minified as to eliminate duplicate rule inclusion)

generate({
  base: 'test/',
  src: 'index.html',
  target: {
    css: 'styles/main.css',
  },
  dimensions: [
    {
      height: 200,
      width: 500,
    },
    {
      height: 900,
      width: 1200,
    },
  ],
});

Generate critical-path CSS and ignore specific selectors

This is a useful option when you e.g. want to defer loading of webfonts or background images.

generate({
  base: 'test/',
  src: 'index.html',
  target: {
    css: 'styles/main.css',
  },
  ignore: {
    atrule: ['@font-face'],
    decl: (node, value) => /url\(/.test(value),
  },
});

Generate critical-path CSS and specify asset rebase behaviour

generate({
  base: 'test/',
  src: 'index.html',
  target: {
    css: 'styles/main.css',
  },
  rebase: {
    from: '/styles/main.css',
    to: '/folder/subfolder/index.html',
  },
});

generate({
  base: 'test/',
  src: 'index.html',
  target: {
    css: 'styles/main.css',
  },
  rebase: (asset) => `https://my-cdn.com${asset.absolutePath}`,
});

Options

| Name | Type | Default | Description | | ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | inline | boolean|object | false | Inline critical-path CSS using filamentgroup's loadCSS. Pass an object to configure inline-critical | | base | string | path.dirname(src) or process.cwd() | Base directory in which the source and destination are to be written | | html | string | | HTML source to be operated against. This option takes precedence over the src option. | | css | array | [] | An array of paths to css files, file globs, Vinyl file objects or source CSS strings. | | src | string | | Location of the HTML source to be operated against | | target | string or object | | Location of where to save the output of an operation. Use an object with 'html' and 'css' props if you want to store both | | width | integer | 1300 | Width of the target viewport

Critical

Install / Use

README