What is url-loader?
The url-loader npm package is used within web development environments to encode files as Base64 URLs and include them inline in the code. It is often used with webpack to handle images, fonts, and other file types within JavaScript and CSS files. When the file size is below a specified limit, url-loader will transform the file into a Data URL; otherwise, it falls back to file-loader, which handles larger files by emitting them to a separate file and returns the file URL.
What are url-loader's main functionalities?
Encode files as Data URLs
This webpack configuration uses url-loader to process image files. If an image is smaller than 8KB, it will be converted to a Base64 encoded Data URL and inlined in the code. Larger images will be handled by file-loader, which is the default fallback.
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192
}
}
]
}
]
}
};
Fallback to file-loader
In this example, url-loader is configured with a fallback option. If the file size exceeds the limit, file-loader is used to emit the file to the output directory and returns the public URL. The 'name' option specifies the naming convention for the emitted files.
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192,
fallback: 'file-loader',
name: '[path][name].[ext]'
}
}
]
}
]
}
};
Other packages similar to url-loader
file-loader
file-loader resolves import/require() on a file into a url and emits the file into the output directory. It is similar to url-loader but does not convert files to Data URLs. It is often used as a fallback for url-loader when files exceed the specified limit.
raw-loader
raw-loader loads files as a string and is similar to url-loader in the sense that it allows the inclusion of file contents inline in the code. However, it does not encode the files to Base64, nor does it have a fallback mechanism like url-loader.
svg-url-loader
svg-url-loader is designed specifically for SVG files. It encodes SVGs into compact Data URLs, similar to what url-loader does for general files. It has optimizations for SVGs, such as removing unnecessary whitespace, newlines, and comments, which url-loader does not perform by default.

url-loader
A loader for webpack which transforms files into base64 URIs.
Getting Started
To begin, you'll need to install url-loader
:
$ npm install url-loader --save-dev
url-loader
works like
file-loader
, but can return
a DataURL if the file is smaller than a byte limit.
index.js
import img from './image.png';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192,
},
},
],
},
],
},
};
And run webpack
via your preferred method.
Options
limit | {Boolean|Number|String} | true | Specifying the maximum size of a file in bytes. |
mimetype | {Boolean|String} | based from mime-types | Sets the MIME type for the file to be transformed. |
encoding | {Boolean|String} | base64 | Specify the encoding which the file will be inlined with. |
generator | {Function} | () => type/subtype;encoding,base64_data | You can create you own custom implementation for encoding data. |
fallback | {String} | file-loader | Specifies an alternative loader to use when a target file's size exceeds the limit. |
esModule | {Boolean} | true | Use ES modules syntax. |
limit
Type: Boolean|Number|String
Default: undefined
The limit can be specified via loader options and defaults to no limit.
Boolean
Enable or disable transform files into base64.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: false,
},
},
],
},
],
},
};
Number|String
A Number
or String
specifying the maximum size of a file in bytes.
If the file size is equal or greater than the limit file-loader
will be used (by default) and all query parameters are passed to it.
Using an alternative to file-loader
is enabled via the fallback
option.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192,
},
},
],
},
],
},
};
mimetype
Type: Boolean|String
Default: based from mime-types
Specify the mimetype
which the file will be inlined with.
If unspecified the mimetype
value will be used from mime-types.
Boolean
The true
value allows to generation the mimetype
part from mime-types.
The false
value removes the mediatype
part from a Data URL (if omitted, defaults to text/plain;charset=US-ASCII
).
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
mimetype: false,
},
},
],
},
],
},
};
String
Sets the MIME type for the file to be transformed.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
mimetype: 'image/png',
},
},
],
},
],
},
};
encoding
Type: Boolean|String
Default: base64
Specify the encoding
which the file will be inlined with.
If unspecified the encoding
will be base64
.
Boolean
If you don't want to use any encoding you can set encoding
to false
however if you set it to true
it will use the default encoding base64
.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.svg$/i,
use: [
{
loader: 'url-loader',
options: {
encoding: false,
},
},
],
},
],
},
};
String
It supports Node.js Buffers and Character Encodings which are ["utf8","utf16le","latin1","base64","hex","ascii","binary","ucs2"]
.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.svg$/i,
use: [
{
loader: 'url-loader',
options: {
encoding: 'utf8',
},
},
],
},
],
},
};
generator
Type: Function
Default: (mimetype, encoding, content, resourcePath) => mimetype;encoding,base64_content
You can create you own custom implementation for encoding data.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|html)$/i,
use: [
{
loader: 'url-loader',
options: {
generator: (content, mimetype, encoding, resourcePath) => {
if (/\.html$/i.test(resourcePath)) {
return `data:${mimetype},${content.toString()}`;
}
return `data:${mimetype}${
encoding ? `;${encoding}` : ''
},${content.toString(encoding)}`;
},
},
},
],
},
],
},
};
fallback
Type: String
Default: 'file-loader'
Specifies an alternative loader to use when a target file's size exceeds the limit set in the limit
option.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
fallback: require.resolve('responsive-loader'),
},
},
],
},
],
},
};
The fallback loader will receive the same configuration options as url-loader.
For example, to set the quality option of a responsive-loader above use:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
fallback: require.resolve('responsive-loader'),
quality: 85,
},
},
],
},
],
},
};
esModule
Type: Boolean
Default: true
By default, file-loader
generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.
You can enable a CommonJS module syntax using:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: 'url-loader',
options: {
esModule: false,
},
},
],
},
],
},
};
Examples
SVG
SVG can be compressed into a more compact output, avoiding base64
.
You can read about it more here.
You can do it using mini-svg-data-uri package.
webpack.config.js
const svgToMiniDataURI = require('mini-svg-data-uri');
module.exports = {
module: {
rules: [
{
test: /\.svg$/i,
use: [
{
loader: 'url-loader',
options: {
generator: (content) => svgToMiniDataURI(content.toString()),
},
},
],
},
],
},
};
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
CONTRIBUTING
License
MIT