# @csstools/postcss-rewrite-url

> Rewrite url values in CSS

Latest version **3.0.0** (published 2026-01-14) · MIT-0 license · 0 weekly downloads

## Install

```sh
npm install @csstools/postcss-rewrite-url
pnpm add @csstools/postcss-rewrite-url
yarn add @csstools/postcss-rewrite-url
bun add @csstools/postcss-rewrite-url
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2026-01-14 |
| First published | 2024-03-17 |
| Weekly downloads | 0 |
| License | MIT-0 |
| TypeScript types | none |
| Module format | ESM |
| Node | >=20.19.0 |
| Dependencies | 2 |
| Unpacked size | 9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1053 |
| Maintainers | jonathantneal, alaguna, romainmenke |
| Keywords | postcss-plugin, rewrite, url |

## Links

- npm: https://www.npmjs.com/package/@csstools/postcss-rewrite-url
- Repository: https://github.com/csstools/postcss-plugins
- Homepage: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-rewrite-url#readme
- Issues: https://github.com/csstools/postcss-plugins/issues
- Funding: https://github.com/sponsors/csstools
- npm.io page: https://npm.io/package/@csstools/postcss-rewrite-url

## Dependencies (2)

- [@csstools/css-tokenizer](https://npm.io/package/@csstools/css-tokenizer.md) ^4.0.0
- [@csstools/css-parser-algorithms](https://npm.io/package/@csstools/css-parser-algorithms.md) ^4.0.0

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 3.0.0 (latest) — 2026-01-14
- 2.1.1 — 2025-05-27
- 2.1.0 — 2024-11-30
- 2.0.4 — 2024-11-01
- 2.0.3 — 2024-10-23
- 2.0.2 — 2024-10-10
- 2.0.1 — 2024-08-18
- 2.0.0 — 2024-08-03
- 1.1.4 — 2024-07-06
- 1.1.3 — 2024-06-29
- 1.1.2 — 2024-05-04
- 1.1.1 — 2024-05-04
- 1.1.0 — 2024-03-19
- 1.0.0 — 2024-03-17

## README

# PostCSS Rewrite URL [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-rewrite-url --save-dev`

[PostCSS Rewrite URL] lets you rewrite url values in CSS.

```css
.foo {
	background: rewrite-url('foo.png');
}

@font-face {
	font-family: "Trickster";
	src:
		local("Trickster"),
		rewrite-url("trickster-COLRv1.otf") format("opentype");
}

/* becomes */

.foo {
	background: url("foo.png#modified");
}

@font-face {
	font-family: "Trickster";
	src:
		local("Trickster"),
		url("trickster-COLRv1.otf#modified") format("opentype");
}
```

## Usage

Add [PostCSS Rewrite URL] to your project:

```bash
npm install postcss @csstools/postcss-rewrite-url --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssRewriteURL = require('@csstools/postcss-rewrite-url');

postcss([
	postcssRewriteURL(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### rewriter

Determine how urls are rewritten with the `rewriter` callback.

```ts
interface ValueToRewrite {
	url: string;
	urlModifiers: Array<string>;
}

interface RewriteContext {
	type: 'declaration-value' | 'at-rule-prelude';
	from: string | undefined;
	rootFrom: string | undefined;
	property?: string;
	atRuleName?: string;
}

type Rewriter = (value: ValueToRewrite, context: RewriteContext) => ValueToRewrite | false;

/** postcss-rewrite-url plugin options */
type pluginOptions = {
	rewriter: Rewriter;
};
```

```js
postcssRewriteURL({
	rewriter: (value, context) => {
		console.log(value); // info about the `rewrite-url()` function itself (e.g. the url and url modifiers)
		console.log(context); // context surrounding the `rewrite-url()` function (i.e. where was it found?)

		if (value.url === 'ignore-me') {
			// return `false` to ignore this url and preserve `rewrite-url()` in the output
			return false;
		}

		// use url modifiers to trigger specific behavior
		if (value.urlModifiers.includes('--a-custom-modifier')) {
			return {
				url: value.url + '#other-modification',
				urlModifiers: [], // pass new or existing url modifiers to emit these in the final result
			};
		}

		return {
			url: value.url + '#modified',
		};
	},
})
```

## Syntax

[PostCSS Rewrite URL] is non-standard and is not part of any official CSS Specification.

### `rewrite-url()` function

The `rewrite-url()` function takes a url string and optional url modifiers and will be transformed to a standard `url()` function by a dev tool.

```css
.foo {
	background: rewrite-url('foo.png');
}
```

```
rewrite-url() = rewrite-url( <string> <url-modifier>* )
```

#### [Stylelint](https://stylelint.io/user-guide/rules/declaration-property-value-no-unknown/#propertiessyntax--property-syntax-)

Stylelint is able to check for unknown property values.
Setting the correct configuration for this rule makes it possible to check even non-standard syntax.

```js
"languageOptions": {
	"syntax": {
		"types": {
			"url": "| rewrite-url( <string> <url-modifier>* )"
		}
	}
},
"rules": {
	"function-no-unknown": [
		true,
		{
			"ignoreFunctions": ["rewrite-url"]
		}
	]
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test

[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-rewrite-url

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Rewrite URL]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-rewrite-url

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