# css-inline
[](https://github.com/Stranger6667/css-inline/actions/workflows/build.yml)
[](https://www.npmjs.com/package/@css-inline/css-inline)
[](https://app.codecov.io/github/Stranger6667/css-inline)
[](https://gitter.im/Stranger6667/css-inline)
`css-inline` is a high-performance library for inlining CSS into HTML 'style' attributes.
This library is designed for scenarios such as preparing HTML emails or embedding HTML into third-party web pages.
For instance, the library transforms HTML like this:
```html
Big Text
```
into:
```html
Big Text
```
- Uses reliable components from Mozilla's Servo project
- Inlines CSS from `style` and `link` tags
- Removes `style` and `link` tags
- Resolves external stylesheets (including local files)
- Optionally caches external stylesheets
- Works on Linux, Windows, and macOS
- Supports HTML5 & CSS3
- Tested on Node.js 20 & 22.
## Playground
If you'd like to try `css-inline`, you can check the WebAssembly-powered [playground](https://css-inline.org/) to see the results instantly.
## Installation
### Node.js
Install with `npm`:
```shell
npm i @css-inline/css-inline
```
## Usage
```typescript
import { inline } from "@css-inline/css-inline";
var inlined = inline(
`
Test
`,
);
// Do something with the inlined HTML, e.g. send an email
```
Note that `css-inline` automatically adds missing `html` and `body` tags, so the output is a valid HTML document.
Alternatively, you can inline CSS into an HTML fragment. Structural tags (``, ``, ``) are stripped from the output; only their contents are preserved. Use `inline` if you need to keep the full document structure:
```javascript
import { inlineFragment } from "@css-inline/css-inline";
var inlined = inlineFragment(
`
Hello
who am i
`,
`
p {
color: red;
}
h1 {
color: blue;
}
`
);
// HTML becomes this:
//
//
Hello
//
//
who am i
//
//
```
### Configuration
- `inlineStyleTags`. Specifies whether to inline CSS from "style" tags. Default: `true`
- `keepStyleTags`. Specifies whether to keep "style" tags after inlining. Default: `false`
- `keepLinkTags`. Specifies whether to keep "link" tags after inlining. Default: `false`
- `keepAtRules`. Specifies whether to keep "at-rules" (starting with `@`) after inlining. Default: `false`
- `minifyCss`. Specifies whether to remove trailing semicolons and spaces between properties and values. Default: `false`
- `baseUrl`. The base URL used to resolve relative URLs. If you'd like to load stylesheets from your filesystem, use the `file://` scheme. Default: `null`
- `loadRemoteStylesheets`. Specifies whether remote stylesheets should be loaded. Default: `true`
- `cache`. Specifies caching options for external stylesheets (for example, `{size: 5}`). Default: `null`
- `extraCss`. Extra CSS to be inlined. Default: `null`
- `preallocateNodeCapacity`. **Advanced**. Preallocates capacity for HTML nodes during parsing. This can improve performance when you have an estimate of the number of nodes in your HTML document. Default: `32`
- `removeInlinedSelectors`. Specifies whether to remove selectors that were successfully inlined from `
Big Text
```
The `data-css-inline="ignore"` attribute also allows you to skip `link` and `style` tags:
```html
Big Text
```
Alternatively, you may keep `style` from being removed by using the `data-css-inline="keep"` attribute.
This is useful if you want to keep `@media` queries for responsive emails in separate `style` tags.
Such tags will be kept in the resulting HTML even if the `keep_style_tags` option is set to `false`.
```html
Big Text
```
Another possibility is to set `keep_at_rules` option to `true`. At-rules cannot be inlined into HTML therefore they
get removed by default. This is useful if you want to keep at-rules, e.g. `@media` queries for responsive emails in
separate `style` tags but inline any styles which can be inlined.
Such tags will be kept in the resulting HTML even if the `keep_style_tags` option is explicitly set to `false`.
```html
Big Text
```
If you set the the `minify_css` option to `true`, the inlined styles will be minified by removing trailing semicolons
and spaces between properties and values.
```html
Big Text
```
You can also cache external stylesheets to avoid excessive network requests:
```typescript
import { inline } from "@css-inline/css-inline";
var inlined = inline(
`
Test
`,
{ cache: { size: 5 } },
);
```
Caching is disabled by default.
## WebAssembly
`css-inline` also ships a WebAssembly module built with `wasm-bindgen` to run in browsers.
```html
```
**NOTE**: WASM module currently lacks support for fetching stylesheets from network or filesystem and caching.
## Performance
`css-inline` is powered by efficient tooling from Mozilla's Servo project and significantly outperforms other JavaScript alternatives in terms of speed.
Most of the time it achieves over a **3x** speed advantage compared to the next fastest alternative.
Here is the performance comparison:
| | Size | `css-inline`| `css-inline-wasm` | `juice` | `inline-css` |
|-------------|---------|-------------|----------------------|-------------------------|-------------------------|
| Basic | 230 B | 8.37 µs | 15.96 µs (**1.91x**) | 42.32 µs (**5.06x**) | 80.85 µs (**9.66x**) |
| Realistic-1 | 8.58 KB | 168.95 µs | 344.59 µs (**2.04x**)| 524.38 µs (**3.10x**) | 1.15 ms (**6.78x**) |
| Realistic-2 | 4.3 KB | 90.36 µs | 180.31 µs (**2.00x**)| 634.52 µs (**7.02x**) | 898.47 µs (**9.94x**) |
| GitHub page | 1.81 MB | 32.73 ms | 119.60 ms (**3.65x**)| 1.60 s (**48.90x**) | 326.41 ms (**9.97x**) |
The "Basic" case was obtained from benchmarking the example from the Usage section.
The benchmarking code is available in the `benches/bench.ts` file. The benchmarks were conducted using the stable `rustc 1.91` on Node.js `v22.21.1`.
## License
This project is licensed under the terms of the [MIT license](https://opensource.org/licenses/MIT).
](https://github.com/Stranger6667/css-inline/actions/workflows/build.yml)
[
](https://www.npmjs.com/package/@css-inline/css-inline)
[
](https://app.codecov.io/github/Stranger6667/css-inline)
[
](https://gitter.im/Stranger6667/css-inline)
`css-inline` is a high-performance library for inlining CSS into HTML 'style' attributes.
This library is designed for scenarios such as preparing HTML emails or embedding HTML into third-party web pages.
For instance, the library transforms HTML like this:
```html