# postcss-url

> PostCSS plugin to rebase or inline on url().

Latest version **10.1.4** (published 2026-05-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-url
pnpm add postcss-url
yarn add postcss-url
bun add postcss-url
```

## Health

**Score 53/100 (C)** — status: active.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 10.1.4 |
| Published | 2026-05-21 |
| First published | 2014-08-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/postcss-url) |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 4 |
| Unpacked size | 32.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 383 |
| Author | Maxime Thirouin |
| Maintainers | moox, sergcen |
| Keywords | css, postcss, postcss-plugin, url, rebase, inline, base64, assets |

## Links

- npm: https://www.npmjs.com/package/postcss-url
- Repository: https://github.com/postcss/postcss-url
- Homepage: https://github.com/postcss/postcss-url#readme
- Issues: https://github.com/postcss/postcss-url/issues
- npm.io page: https://npm.io/package/postcss-url

## Dependencies (4)

- [mime](https://npm.io/package/mime.md) ~2.5.2
- [make-dir](https://npm.io/package/make-dir.md) ~3.1.0
- [xxhashjs](https://npm.io/package/xxhashjs.md) ~0.2.2
- [minimatch](https://npm.io/package/minimatch.md) ^3.1.5

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 10.1.4 (latest) — 2026-05-21
- 9.0.0 (beta) — 2019-04-16
- 10.1.3 — 2021-03-19
- 10.1.2 — 2021-03-19
- 10.1.1 — 2020-11-26
- 10.1.0 — 2020-11-04
- 10.0.0 — 2020-10-23
- 8.0.0 — 2018-08-09
- 7.3.2 — 2018-04-03
- 7.3.1 — 2018-02-25
- 7.3.0 — 2017-11-25
- 7.2.1 — 2017-11-19
- 7.2.0 — 2017-11-17
- 7.1.2 — 2017-08-11
- 7.1.1 — 2017-07-24
- … 40 more at https://npm.io/package/postcss-url/versions

## README

# postcss-url

[![Travis Build Status](https://img.shields.io/travis/postcss/postcss-url/master.svg?label=unix%20build)](https://travis-ci.org/postcss/postcss-url)
[![AppVeyor Build Status](https://img.shields.io/appveyor/ci/MoOx/postcss-url/master.svg?label=windows%20build)](https://ci.appveyor.com/project/MoOx/postcss-url)
[![dependencies Status](https://david-dm.org/postcss/postcss-url/status.svg)](https://david-dm.org/postcss/postcss-url)
[![devDependencies Status](https://david-dm.org/postcss/postcss-url/dev-status.svg)](https://david-dm.org/postcss/postcss-url?type=dev)

> [PostCSS](https://github.com/postcss/postcss) plugin to rebase, inline or copy on url().

## Installation

```console
$ npm install postcss postcss-url
```

## Basic example - rebase

```js
// dependencies
const fs = require("fs")
const postcss = require("postcss")
const url = require("postcss-url")

// css to be processed
const css = fs.readFileSync("input.css", "utf8")

// process css
const output = postcss()
  .use(url({
    url: "rebase"
  }))
  .process(css, {
    from: "src/stylesheet/index.css",
    to: "dist/index.css"
  })
```
before:
```css
.element {
    background: url('images/sprite.png');
}
```
after:
```css
.element {
    /* rebasing path by new destination */
    background: url('../src/stylesheet/images/sprite.png');
}
```


## Inline
```js
// postcss-url options
const options = {
    url: 'inline'
};

postcss()
  .use(url(options))
  .process(css, {
    from: "src/stylesheet/index.css",
    to: "dist/index.css"
  })
```
before:
```css
.element {
    background: url('/images/sprite.png');
    filter: url('/images/circle.svg');
}
```
after:
```css
.element {
    /* inlined png as base64 */
    background: url('data:image/png;base64,R0lGODlhAQABAJH/AP///wAAAP///wAAACH/C0FET0JFOklSMS4');
    /* inlined svg as encodeURIComponent */
    filter: url('data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E');
}
```

## Copy
```js
// postcss-url options
const options = {
    url: 'copy',
    // base path to search assets from
    basePath: path.resolve('node_modules/bootstrap'),
    // dir to copy assets
    assetsPath: 'img',
    // using hash names for assets (generates from asset content)
    useHash: true
};

postcss()
  .use(url(options))
  .process(css, {
    from: "src/stylesheet/index.css",
    to: "dist/index.css"
  })
```
before:
```css
.element {
    background: url('/images/sprite.png');
}
```
after:
```css
.element {
    /* copy 'sprite.png' from 'node_modules/bootstrap/images/' to 'dist/img/' */
    /* and rename it by hash function */
    background: url('img/a2ds3kfu.png');
}
```

### Multiple options

process first matched option by default.
```multi: true``` in `custom` will processing with other options

```js
const options = [
    { filter: '**/assets/copy/*.png', url: 'copy', assetsPath: 'img', useHash: true },
    { filter: '**/assets/inline/*.svg', url: 'inline' },
    { filter: '**/assets/**/*.gif', url: 'rebase' },
    // using custom function to build url
    { filter: 'cdn/**/*', url: (asset) => `https://cdn.url/${asset.url}` }
];

postcss().use(url(options))
```

Checkout [tests](test) for examples.

### Options combinations

* `rebase` - _default_
  * `assetsPath` - directory to copy assets (relative to `to` or absolute)
* `inline`
  * `basePath` - path or array of paths to search assets (relative to `from`, or absolute)
  * `encodeType` - `base64`, `encodeURI`, `encodeURIComponent`
  * `includeUriFragment` - include the fragment identifer at the end of the URI
  * `maxSize` - file size in kbytes
  * `fallback` - `copy`, `rebase` or custom function for files > `maxSize`
  * `ignoreFragmentWarning` - do not warn when an SVG URL with a fragment is inlined
  * `optimizeSvgEncode` - reduce size of inlined svg (IE9+, Android 3+)
* `copy`
    * `basePath` - path or array of paths to search assets (relative to `from`, or absolute)
    * `assetsPath` - directory to copy assets (relative to `to` or absolute)
    * `useHash` - use filehash(xxhash) for naming
    * `hashOptions` - options for hash function
* `custom {Function}`
    * `multi` - processing with other options

### Options list

#### `url`
##### `rebase` - _(default)_
Allow you to fix `url()` according to postcss `to` and/or `from` options (rebase to `to` first if available, otherwise `from` or `process.cwd()`).
##### `inline` 
Allow you to inline assets using base64 encoding. Can use postcss `from` option to find ressources.
##### `copy`
Allow you to copy and rebase assets according to postcss `to`, `assetsPath` and `from` options (`assetsPath` is relative to the option `to`).
##### `url: {Function}`
Custom transform function. Takes following arguments:
* `asset`
  * `url` - original url
  * `pathname` - url pathname (url without search or hash)
  * `absolutePath` - absolute path to asset
  * `relativePath` - current relative path to asset
  * `search` - _search_ from `url`, ex. `?query=1` from `./image.png?query=1`
  * `hash` - _hash_ from `url`, ex. `#spriteLink` from `../asset.svg#spriteLink`
* `dir`
  * `from` - postcss option from
  * `to` - postcss option to
  * `file` - decl file path
* `options` - postcss-url matched options
* `decl` - related postcss declaration object
* `warn` - wrapped function `result.warn` for current `decl`
* `result` – postcss result object

And should return the transformed url.
You can use this option to adjust urls for CDN.

#### `maxSize`

Specify the maximum file size to inline (in kbytes)

#### `ignoreFragmentWarning`
_(default: `false`)_

Do not warn when an SVG URL with a fragment is inlined.
PostCSS-URL does not support partial inlining.  The entire SVG file will be inlined.  By default a warning will be issued when this occurs.

**NOTE:** Only files less than the maximum size will be inlined.

#### `filter`

A regular expression e.g. `/\.svg$/`, a [minimatch string](https://github.com/isaacs/minimatch) e.g. `'**/*.svg'` or a custom filter function to determine wether a file should be inlined.

#### `fallback`

The url fallback method to use if max size is exceeded or url contains a hash.
Custom transform functions are supported.

#### `includeUriFragment`
_(default: `false`)_

Specifies whether the URL's fragment identifer value, if present, will be added
to the inlined data URI.

#### `basePath`

Specify the base path or list of base paths where to search images from

#### `assetsPath`

_(default: `false`)_

If you specify an `assetsPath`, the assets files will be copied in that
destination

#### `useHash`

_(default: `false`)_

If set to `true` the copy method is going to rename the path of the files by a hash name

#### `hashOptions`

##### `method`

_(default: `xxhash32`)_

Hash method `xxhash32|xxhash64` or custom function (accept file buffer)
##### `shrink`

_(default: `8`)_

Result hash shrink count
##### `append`

_(default: `false`)_

Prepend the original filename in resulting filename

---

## Contributing

Work on a branch, install dev-dependencies, respect coding style & run tests before submitting a bug fix or a feature.

```console
$ git clone https://github.com/postcss/postcss-url.git
$ git checkout -b patch-1
$ npm install
$ npm test
```

## [Changelog](CHANGELOG.md)

## [License](LICENSE)

---
_Source: https://npm.io/package/postcss-url · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._