# Inline CSS (inline_css)

Inlines small external CSS into HTML. How the mod_pagespeed inline_css filter works, when to use it, its risks and the Apache, nginx and IIS directives.

Canonical URL: https://modpagespeed.com/docs/filters/inline_css/

- Category: CSS
- CoreFilters: Yes
- OptimizeForBandwidth: No
- Risk: Generally safe

`inline_css` replaces a small external stylesheet with an inline `<style>` block holding the file's contents, so first paint no longer waits on that fetch. Relative `url()` paths inside the stylesheet are made absolute first, so images and fonts keep resolving from the page's location. Live demo: [inline_css](https://modpagespeed.com/examples/inline_css/).

## How it works

### When it helps and when it does not

CSS is render-blocking, so for a tiny stylesheet the removed round trip is worth more than the bytes: the request, its headers, and its connection setup all cost more than a kilobyte of inline text. The trade flips as files grow or get shared. An inlined stylesheet is not cached on its own, so it downloads again with every page view, and a file inlined into twenty pages is transferred twenty times. Stylesheets shared across many pages, and anything well above the threshold, are better left external with a long cache lifetime. `inline_css` is a CoreFilter, so the trade is already live on a default install.

### How it decides

Only stylesheets whose contents are no larger than `CssInlineMaxBytes` (default 2048 bytes) qualify, and only files on domains the module is authorized to fetch. A stylesheet whose `media` attribute cannot affect the screen, such as `print`, stays external: inlining it would make every page pay for rules no screen visitor needs. A file that contains the text `</style>` stays external too, since it would end the inline block early. Nothing is inlined when the page's Content-Security-Policy forbids inline styles.

## When to use it

- In CoreFilters, the default RewriteLevel: it runs unless you disable it.
- Risk rating on these docs: **Generally safe**.

## Risks

- The page grows by the stylesheet's size on every view, so keep `CssInlineMaxBytes` small. Raising it to inline a large file delays the HTML itself, which is worse than the fetch it removes.

- Verify with the `X-Mod-Pagespeed` response header and a `?PageSpeedFilters=-inline_css` comparison; [Is it working?](https://modpagespeed.com/docs/is-it-working/) has the steps.

## Configuration

Enable it in the module configuration, at server, virtual-host or location scope:

**Apache**

```apache
ModPagespeedEnableFilters inline_css
```

**nginx**

```nginx
pagespeed EnableFilters inline_css;
```

**IIS (pagespeed.config)**

```text
pagespeed EnableFilters inline_css
```

It is on by default under CoreFilters; to turn it off:

```text
ModPagespeedDisableFilters inline_css   # Apache
pagespeed DisableFilters inline_css;   # nginx
pagespeed DisableFilters inline_css   # IIS
```

```text
<!-- before: a render-blocking request for a 1.8 KB file -->
<link rel="stylesheet" href="/css/header.css">

<!-- after: the rules sit inside the page -->
<style>.site-header{display:flex;gap:1rem}.site-header img{height:2rem}</style>
```

```apache
# Apache
ModPagespeedEnableFilters inline_css
ModPagespeedCssInlineMaxBytes 2048
```

```nginx
# Nginx
pagespeed EnableFilters inline_css;
pagespeed CssInlineMaxBytes 2048;
```

Scoping, `ForbidFilters` and the thresholds filters read: [Choosing filters](https://modpagespeed.com/docs/filter-selection/).

## Live example

See the before and after, with the source diff: [inline_css example](https://modpagespeed.com/examples/inline_css/).

## Frequently asked questions

**What does the inline_css filter do?**

`inline_css` replaces a small external stylesheet with an inline `<style>` block holding the file's contents, so first paint no longer waits on that fetch. Relative `url()` paths inside the stylesheet are made absolute first, so images and fonts keep resolving from the page's location. Live demo: inline_css.

**Is inline_css enabled by default?**

Yes. `inline_css` is in CoreFilters, the default RewriteLevel, so it runs unless you turn it off with `DisableFilters`.

**How do I turn off inline_css?**

Add `ModPagespeedDisableFilters inline_css` on Apache or `pagespeed DisableFilters inline_css;` on nginx. On IIS, add `pagespeed DisableFilters inline_css` to pagespeed.config.

## Related filters

- [`prioritize_critical_css`](https://modpagespeed.com/docs/filters/prioritize_critical_css/): Prioritize critical CSS
- [`combine_css`](https://modpagespeed.com/docs/filters/combine_css/): Combine CSS
- [`rewrite_css`](https://modpagespeed.com/docs/filters/rewrite_css/): Minify CSS
- [`inline_javascript`](https://modpagespeed.com/docs/filters/inline_javascript/): Inline JavaScript
- [`compute_critical_css`](https://modpagespeed.com/docs/filters/compute_critical_css/): Compute critical CSS
- [`extend_cache_css`](https://modpagespeed.com/docs/filters/extend_cache_css/): Extend cache for CSS
- [`fallback_rewrite_css_urls`](https://modpagespeed.com/docs/filters/fallback_rewrite_css_urls/): Fallback CSS URL rewriting
- [`flatten_css_imports`](https://modpagespeed.com/docs/filters/flatten_css_imports/): Flatten CSS @imports

This page is drawn from the [inline_css entry on CSS filters](https://modpagespeed.com/docs/css-filters/#inline_css). Every filter in one table: [PageSpeed filters](https://modpagespeed.com/docs/filters/).