Inline CSS

Configuration

The 'Inline CSS' filter is enabled by specifying:

Apache:
ModPagespeedEnableFilters inline_css
Nginx:
pagespeed EnableFilters inline_css;

in the configuration file.

When this filter is enabled, you may also enable the following setting:

Apache:
ModPagespeedCssInlineMaxBytes bytes
Nginx:
pagespeed CssInlineMaxBytes bytes;

This is the maximum size in bytes of any CSS file that will be inlined.

Description

The "Inline CSS" filter reduces the number of requests made by a web page by inserting the contents of small external CSS resources directly into the HTML document. This can reduce the time it takes to display content to the user, especially in older browsers.

Operation

When the 'Inline CSS' filter is enabled, The contents of small external CSS resources are written directly into the HTML document; therefore the browser does not request those CSS resources independently.

For example, if the HTML document looks like this:

<html>
  <head>
    <link rel="stylesheet" href="small.css">
  </head>
  <body>
    <div class="blue yellow big bold">
      Hello, world!
    </div>
  </body>
</html>

And the resource small.css is like this:

  .yellow {background-color: yellow;}
  .blue {color: blue;}
  .big { font-size: 8em; }
  .bold { font-weight: bold; }

Then PageSpeed will rewrite it into:

<html>
  <head>
    <style>
      .yellow {background-color: yellow;}
      .blue {color: blue;}
      .big { font-size: 8em; }
      .bold { font-weight: bold; }
    </style>
    </head>
  <body>
    <div class="blue yellow big bold">
      Hello, world!
    </div>
  </body>
</html>

This eliminates the browser request to small.css by placing its contents inline in the HTML document.

Example

You can see the filter in action at www.modpagespeed.com on this example.

Note

CSS may contain URLs that are relative to the location of the CSS file. To avoid breaking such URLs, the 'Inline CSS' filter will attempt to rewrite them into absolute URLs when it performs the inlining.

Requirements

There is a tradeoff here between requests and cacheability: including the CSS directly in the HTML avoids making an additional request to the external CSS resource, but if the CSS file is large (and doesn't change often), it may be better to keep it separate from the HTML so that it can be cached by the browser. Thus, the Inline CSS filter will only inline CSS files below a certain size threshold, which can be adjusted using the CssInlineMaxBytes directive.

It is possible for CSS files to contain small snippets of JavaScript code, at least for certain browsers. To avoid opening up cross-domain scripting vulnerabilities, the Inline CSS filter will only inline an external CSS file if it is being served from the same domain as the HTML file into which it is to be inlined.

Risks

The 'Inline CSS' filter is low to moderate risk. It should be safe for most pages, but it could potentially break scripts that walk the DOM looking for and examining <link> or <style> tags.