Transform `url()` in css

Usage no npm install needed!

<script type="module">
  import postcssCustomUrl from '';



version status dependencies devDependencies license node

Transform url() in css.


var url = require('postcss-custom-url')
var util = url.util

var postcss = require('postcss')
var path = require('path')
var fixtures = path.resolve.bind(path, __dirname, 'fixtures')

  [ util.inline, { maxSize: 5 } ],
  // equivalent with util.copy
  [ 'copy', { assetOutFolder: fixtures('build', 'images') } ],
  '.a{ background-image: url(images/octocat_setup.png); }',
  { from: fixtures('a.css'), to: fixtures('build', 'css', 'a.css') }
.then(function (result) {
  // '.a{ background-image: url(../images/octocat_setup.png); }'



Type: Array

Default: [ util.rebase ]

An array of transforms.

If an element is not a function, it should be the name of a method exported by util: 'copy', 'inline', 'rebase'.


Type: Function, Array

Signature: transformFn(result, ...args)

Function to transform url, through modifying result.url

If Array, the first element should be the transform function, and elements after the first will be treated as its arguments args.


Type: Result


Properties and methods:

  • url: String
  • from: The CSS source path
  • to: The CSS destination path
  • file: The asset source path
  • asset: Asset.
  • isRelative(): Function
  • Result.getFile(url, opts). Return the file property.
  • Result.dataUrl(file)


Properties and methods:

  • mimeType
  • size(): Return a promise to get the size of the asset
  • data(): Return a promise to get the contents of the asset
  • shasum(): Return a promise to get the sha1 of the contents of the asset
  • base64(): Return a promise to get the base64 of the contents of the asset
  • dataUrl(): Return a promise to get the data url of the asset


A group of transform methods.


Transform result.url according to


Transform result.url to data-url.


  • maxSize: Number, default: 10. Specify the maximum file size to inline (in kbytes)


Copy asset files to proper destinations and transform result.url.


  • useHash: Boolean, default: false. If true, assets are renamed by their sha1 hashes.
  • name: String, default: null. Specify how to rename the asset. It only works when useHash is false. Special patterns:
    • [name]: replaced with the basename of the asset, without the extension.
    • [hash]: replaced with the hash
  • assetOutFolder: String, Function. Specify the destination where assets should be copied. If Function, it receives the asset file path and result.opts, and should return the output folder. Urls are transformed based on the destination, unless baseUrl is specified.
  • baseUrl: String, default: null. Specify the base url for assets.
var url = require('postcss-custom-url')
var postcss = require('postcss')

      // copy images to /path/to/build/images
      // since the final css file is /path/to/build/css/style.css,
      // url is set to ../images/octocat_setup.84f6371.png
      assetOutFolder: '/path/to/build/images',

      // rename images like octocat_setup.84f6371.png
      name: '[name].[hash]',

      // if set to true, all images are named after `[hash]`
      // useHash: true,

      // if specified, reset url to i/octocat_setup.84f6371.png
      // baseUrl: 'i',
  '.a{ background-image: url(images/octocat_setup.png); }',
  { from: '/path/to/src/style.css', to: '/path/to/build/css/style.css' }
.then(function (result) {
  // '.a{ background-image: url(../images/octocat_setup.png); }'