html-loader
Advanced tools
Supply Chain Security
Vulnerability
Quality
Maintenance
License
The html-loader npm package is used to export HTML as string. When used with webpack, it allows you to require HTML files as modules. It can also minimize the HTML when the webpack 'minimize' option is enabled. It's useful for processing HTML files to include them as part of your JavaScript bundle.
Export HTML as String
Allows you to use HTML files as modules by exporting them as strings. This can be useful when you want to include your HTML in your JavaScript files.
require('html-loader!./file.html')Interpolate Custom Syntax
Enables interpolation with a custom syntax within the HTML file. This is useful for including images or other assets using a require statement.
require('html-loader?interpolate=require!./file.html')Minimize HTML
When used with webpack, you can minimize the HTML by setting the 'minimize' option to true. This helps reduce the size of the HTML included in your JavaScript bundle.
module.exports = { module: { rules: [{ test: /\.html$/, use: [{ loader: 'html-loader', options: { minimize: true } }] }] } }The raw-loader package is similar to html-loader in that it allows you to import files as a string. However, it does not specifically target HTML files and does not have HTML-specific features like minimizing.
The handlebars-loader is used for compiling Handlebars templates and includes them in the webpack bundle. It's similar to html-loader but is tailored for Handlebars template syntax.
The pug-loader package allows you to compile Pug templates and include them in your webpack bundle. It's similar to html-loader but is designed for the Pug templating engine (formerly known as Jade).
Exports HTML as string. HTML is minimized when the compiler demands.
To begin, you'll need to install html-loader:
npm install --save-dev html-loader
or
yarn add -D html-loader
or
pnpm add -D html-loader
Then add the plugin to your webpack config. For example:
file.js
import html from "./file.html";
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
},
],
},
};
sourcesType:
type sources =
| boolean
| {
list?: Array<{
tag?: string;
attribute?: string;
type?: string;
filter?: (
tag: string,
attribute: string,
attributes: string,
resourcePath: string,
) => boolean;
}>;
urlFilter?: (
attribute: string,
value: string,
resourcePath: string,
) => boolean;
scriptingEnabled?: boolean;
};
Default: true
By default every loadable attribute (for example - <img src="image.png">) is imported (const img = require('./image.png') or new URL("./image.png", import.meta.url)).
You may need to specify loaders for images in your configuration (recommended asset modules).
Supported tags and attributes:
src attribute of the audio tagsrc attribute of the embed tagsrc attribute of the img tagsrcset attribute of the img tagsrc attribute of the input tagdata attribute of the object tagsrc attribute of the script taghref attribute of the script tagxlink:href attribute of the script tagsrc attribute of the source tagsrcset attribute of the source tagsrc attribute of the track tagposter attribute of the video tagsrc attribute of the video tagxlink:href attribute of the image taghref attribute of the image tagxlink:href attribute of the use taghref attribute of the use taghref attribute of the link tag when the rel attribute contains stylesheet, icon, shortcut icon, mask-icon, apple-touch-icon, apple-touch-icon-precomposed, apple-touch-startup-image, manifest, prefetch, preload or when the itemprop attribute is image, logo, screenshot, thumbnailurl, contenturl, downloadurl, duringmedia, embedurl, installurl, layoutimageimagesrcset attribute of the link tag when the rel attribute contains stylesheet, icon, shortcut icon, mask-icon, apple-touch-icon, apple-touch-icon-precomposed, apple-touch-startup-image, manifest, prefetch, preloadcontent attribute of the meta tag when the name attribute is msapplication-tileimage, msapplication-square70x70logo, msapplication-square150x150logo, msapplication-wide310x150logo, msapplication-square310x310logo, msapplication-config, twitter:image or when the property attribute is og:image, og:image:url, og:image:secure_url, og:audio, og:audio:secure_url, og:video, og:video:secure_url, vk:image or when the itemprop attribute is image, logo, screenshot, thumbnailurl, contenturl, downloadurl, duringmedia, embedurl, installurl, layoutimageicon-uri value component in content attribute of the meta tag when the name attribute is msapplication-taskbooleanThe true value enables the processing of all default elements and attributes, the false value disables the processing of all attributes.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
// Disables attributes processing
sources: false,
},
},
],
},
};
objectAllows you to specify which tags and attributes to process, filter them, filter urls and process sources starting with /.
For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
sources: {
list: [
// All default supported tags and attributes
"...",
{
tag: "img",
attribute: "data-src",
type: "src",
},
{
tag: "img",
attribute: "data-srcset",
type: "srcset",
},
],
urlFilter: (attribute, value, resourcePath) => {
// The `attribute` argument contains a name of the HTML attribute.
// The `value` argument contains a value of the HTML attribute.
// The `resourcePath` argument contains a path to the loaded HTML file.
if (/example\.pdf$/.test(value)) {
return false;
}
return true;
},
},
},
},
],
},
};
listType:
type list = Array<{
tag?: string;
attribute?: string;
type?: string;
filter?: (
tag: string,
attribute: string,
attributes: string,
resourcePath: string,
) => boolean;
}>;
Default: supported tags and attributes.
Allows to setup which tags and attributes to process and how, as well as the ability to filter some of them.
Using ... syntax allows you to extend default supported tags and attributes.
For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
sources: {
list: [
// All default supported tags and attributes
"...",
{
tag: "img",
attribute: "data-src",
type: "src",
},
{
tag: "img",
attribute: "data-srcset",
type: "srcset",
},
{
// Tag name
tag: "link",
// Attribute name
attribute: "href",
// Type of processing, can be `src` or `scrset`
type: "src",
// Allow to filter some attributes
filter: (tag, attribute, attributes, resourcePath) => {
// The `tag` argument contains a name of the HTML tag.
// The `attribute` argument contains a name of the HTML attribute.
// The `attributes` argument contains all attributes of the tag.
// The `resourcePath` argument contains a path to the loaded HTML file.
if (/my-html\.html$/.test(resourcePath)) {
return false;
}
if (!/stylesheet/i.test(attributes.rel)) {
return false;
}
if (
attributes.type &&
attributes.type.trim().toLowerCase() !== "text/css"
) {
return false;
}
return true;
},
},
],
},
},
},
],
},
};
If the tag name is not specified it will process all the tags.
You can use your custom filter to specify html elements to be processed.
For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
sources: {
list: [
{
// Attribute name
attribute: "src",
// Type of processing, can be `src` or `scrset`
type: "src",
// Allow to filter some attributes (optional)
filter: (tag, attribute, attributes, resourcePath) => {
// The `tag` argument contains a name of the HTML tag.
// The `attribute` argument contains a name of the HTML attribute.
// The `attributes` argument contains all attributes of the tag.
// The `resourcePath` argument contains a path to the loaded HTML file.
// choose all HTML tags except img tag
return tag.toLowerCase() !== "img";
},
},
],
},
},
},
],
},
};
Filter can also be used to extend the supported elements and attributes.
For example, filter can help process meta tags that reference assets:
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
sources: {
list: [
{
tag: "meta",
attribute: "content",
type: "src",
filter: (tag, attribute, attributes, resourcePath) => {
if (
attributes.value === "og:image" ||
attributes.name === "twitter:image"
) {
return true;
}
return false;
},
},
],
},
},
},
],
},
};
[!NOTE]
source with a
tagoption takes precedence over source without.
Filter can be used to disable default sources.
For example:
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
sources: {
list: [
"...",
{
tag: "img",
attribute: "src",
type: "src",
filter: () => false,
},
],
},
},
},
],
},
};
urlFilterType:
type urlFilter = (
attribute: string,
value: string,
resourcePath: string,
) => boolean;
Default: undefined
Allow to filter urls. All filtered urls will not be resolved (left in the code as they were written).
Non-requestable sources (for example <img src="javascript:void(0)">) are not handled by default.
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
sources: {
urlFilter: (attribute, value, resourcePath) => {
// The `attribute` argument contains a name of the HTML attribute.
// The `value` argument contains a value of the HTML attribute.
// The `resourcePath` argument contains a path to the loaded HTML file.
if (/example\.pdf$/.test(value)) {
return false;
}
return true;
},
},
},
},
],
},
};
scriptingEnabledType:
type scriptingEnabled = boolean;
Default: true
By default, the parser in html-loader interprets content inside <noscript> tags as #text, so processing of content inside this tag will be ignored.
In order to enable processing inside <noscript> for content recognition by the parser as #AST, set this parameter to: false
Additional information: scriptingEnabled
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
sources: {
// Enables processing inside the <noscript> tag
scriptingEnabled: false,
},
},
},
],
},
};
preprocessorType:
type preprocessor = (content: string, loaderContext: LoaderContext) => string;
Default: undefined
Allows pre-processing of content before handling.
[!WARNING]
You should always return valid HTML
file.hbs
<div>
<p>{{firstname}} {{lastname}}</p>
<img src="image.png" alt="alt" />
<div>
functionYou can set the preprocessor option as a function instance.
webpack.config.js
const Handlebars = require("handlebars");
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: "html-loader",
options: {
preprocessor: (content, loaderContext) => {
let result;
try {
result = Handlebars.compile(content)({
firstname: "Value",
lastname: "OtherValue",
});
} catch (error) {
loaderContext.emitError(error);
return content;
}
return result;
},
},
},
],
},
};
You can also set the preprocessor option as an asynchronous function instance.
For example:
webpack.config.js
const Handlebars = require("handlebars");
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: "html-loader",
options: {
preprocessor: async (content, loaderContext) => {
let result;
try {
result = await Handlebars.compile(content)({
firstname: "Value",
lastname: "OtherValue",
});
} catch (error) {
await loaderContext.emitError(error);
return content;
}
return result;
},
},
},
],
},
};
postprocessorType:
type postprocessor = (content: string, loaderContext: LoaderContext) => string;
Default: undefined
Allows post-processing of content after replacing all attributes (like src/srcset/etc).
file.html
<img src="image.png" />
<img src="<%= 'Hello ' + (1+1) %>" />
<img src="<%= require('./image.png') %>" />
<img src="<%= new URL('./image.png', import.meta.url) %>" />
<div><%= require('./gallery.html').default %></div>
functionYou can set the postprocessor option as a function instance.
webpack.config.js
const Handlebars = require("handlebars");
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
postprocessor: (content, loaderContext) => {
// When you environment supports template literals (using browserslist or options) we will generate code using them
const isTemplateLiteralSupported = content[0] === "`";
return content
.replace(/<%=/g, isTemplateLiteralSupported ? `\${` : '" +')
.replace(/%>/g, isTemplateLiteralSupported ? "}" : '+ "');
},
},
},
],
},
};
You can also set the postprocessor option as an asynchronous function instance.
For example:
webpack.config.js
const Handlebars = require("handlebars");
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: "html-loader",
options: {
postprocessor: async (content, loaderContext) => {
const value = await getValue();
// When you environment supports template literals (using browserslist or options) we will generate code using them
const isTemplateLiteralSupported = content[0] === "`";
return content
.replace(/<%=/g, isTemplateLiteralSupported ? `\${` : '" +')
.replace(/%>/g, isTemplateLiteralSupported ? "}" : '+ "')
.replace("my-value", value);
},
},
},
],
},
};
minimizeType:
type minimize =
| boolean
| {
caseSensitive?: boolean;
collapseWhitespace?: boolean;
conservativeCollapse?: boolean;
keepClosingSlash?: boolean;
minifyCSS?: boolean;
minifyJS?: boolean;
removeComments?: boolean;
removeRedundantAttributes?: boolean;
removeScriptTypeAttributes?: boolean;
removeStyleLinkTypeAttributes?: boolean;
};
Default: true in production mode, otherwise false
Tell html-loader to minimize HTML.
booleanThe enabled rules for minimizing by default are the following ones:
({
caseSensitive: true,
collapseWhitespace: true,
conservativeCollapse: true,
keepClosingSlash: true,
minifyCSS: true,
minifyJS: true,
removeComments: true,
removeRedundantAttributes: true,
removeScriptTypeAttributes: true,
removeStyleLinkTypeAttributes: true,
});
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
minimize: true,
},
},
],
},
};
objectwebpack.config.js
See html-minifier-terser's documentation for more information on the available options.
The default rules can be overridden using the following options in your webpack.conf.js
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
minimize: {
removeComments: false,
collapseWhitespace: false,
},
},
},
],
},
};
The default rules can be extended:
webpack.config.js
const { defaultMinimizerOptions } = require("html-loader");
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
minimize: {
...defaultMinimizerOptions,
removeComments: false,
collapseWhitespace: false,
},
},
},
],
},
};
esModuleType:
type esModule = boolean;
Default: true
By default, html-loader generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, such as module concatenation and tree shaking.
You can enable a CommonJS modules syntax using:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {
esModule: false,
},
},
],
},
};
<!-- webpackIgnore: true --> commentWith <!-- webpackIgnore: true --> comment, one can disable sources handling for next tag.
<!-- Disabled url handling for the src attribute -->
<!-- webpackIgnore: true -->
<img src="image.png" />
<!-- Disabled url handling for the src and srcset attributes -->
<!-- webpackIgnore: true -->
<img
srcset="image.png 480w, image.png 768w"
src="image.png"
alt="Elva dressed as a fairy"
/>
<!-- Disabled url handling for the content attribute -->
<!-- webpackIgnore: true -->
<meta itemprop="image" content="./image.png" />
<!-- Disabled url handling for the href attribute -->
<!-- webpackIgnore: true -->
<link rel="icon" type="image/png" sizes="192x192" href="./image.png" />
With resolve.roots one can specify a list of directories where requests of server-relative URLs (starting with '/') are resolved.
webpack.config.js
module.exports = {
context: __dirname,
module: {
rules: [
{
test: /\.html$/i,
loader: "html-loader",
options: {},
},
{
test: /\.jpg$/,
type: "asset/resource",
},
],
},
resolve: {
roots: [path.resolve(__dirname, "fixtures")],
},
};
file.html
<img src="/image.jpg" />
// => image.jpg in __dirname/fixtures will be resolved
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.jpg$/,
type: "asset/resource",
},
{
test: /\.png$/,
type: "asset/inline",
},
],
},
output: {
publicPath: "http://cdn.example.com/[fullhash]/",
},
};
file.html
<img src="image.jpg" data-src="image2x.png" />
index.js
require("html-loader!./file.html");
// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="image2x.png">'
require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
// => '<img src="image.jpg" data-src="data:image/png;base64,..." >'
require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"src","type":"src"},{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="data:image/png;base64,..." >'
script and link tagsscript.file.js
console.log(document);
style.file.css
a {
color: red;
}
file.html
<!doctype html>
<html>
<head>
<meta charset="UTF-8" />
<title>Title of the document</title>
<link rel="stylesheet" type="text/css" href="./style.file.css" />
</head>
<body>
Content of the document......
<script src="./script.file.js"></script>
</body>
</html>
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/,
type: "asset/resource",
generator: {
filename: "[name][ext]",
},
},
{
test: /\.html$/i,
use: ["html-loader"],
},
{
test: /\.js$/i,
exclude: /\.file.js$/i,
loader: "babel-loader",
},
{
test: /\.file.js$/i,
type: "asset/resource",
},
{
test: /\.css$/i,
exclude: /\.file.css$/i,
loader: "css-loader",
},
{
test: /\.file.css$/i,
type: "asset/resource",
},
],
},
};
You can use any template system. Below is an example for handlebars.
file.hbs
<div>
<p>{{firstname}} {{lastname}}</p>
<img src="image.png" alt="alt" />
<div>
webpack.config.js
const Handlebars = require("handlebars");
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: "html-loader",
options: {
preprocessor: (content, loaderContext) => {
let result;
try {
result = Handlebars.compile(content)({
firstname: "Value",
lastname: "OtherValue",
});
} catch (error) {
loaderContext.emitError(error);
return content;
}
return result;
},
},
},
],
},
};
You can use PostHTML without any additional loaders.
file.html
<img src="image.jpg" />
webpack.config.js
const posthtml = require("posthtml");
const posthtmlWebp = require("posthtml-webp");
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: "html-loader",
options: {
preprocessor: (content, loaderContext) => {
let result;
try {
result = posthtml().use(plugin).process(content, { sync: true });
} catch (error) {
loaderContext.emitError(error);
return content;
}
return result.html;
},
},
},
],
},
};
A very common scenario is exporting the HTML into their own .html file, to serve them directly instead of injecting with javascript.
This can be achieved with a combination of html-loader and asset modules.
The html-loader will parse the URLs, require the images and everything you
expect. The extract loader will parse the javascript back into a proper html
file, ensuring images are required and point to proper path, and the asset modules
will write the .html file for you. Example:
webpack.config.js
module.exports = {
output: {
assetModuleFilename: "[name][ext]",
},
module: {
rules: [
{
test: /\.html$/,
type: "asset/resource",
generator: {
filename: "[name][ext]",
},
},
{
test: /\.html$/i,
use: ["html-loader"],
},
],
},
};
Please take a moment to read our contributing guidelines if you haven't yet done so.
FAQs
Html loader module for webpack
The npm package html-loader receives a total of 1,068,272 weekly downloads. As such, html-loader popularity was classified as popular.
We found that html-loader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious PyPI package semantic-types steals Solana private keys via transitive dependency installs using monkey patching and blockchain exfiltration.
Security News
New CNA status enables OpenJS Foundation to assign CVEs for security vulnerabilities in projects like ESLint, Fastify, Electron, and others, while leaving disclosure responsibility with individual maintainers.
Product
Socket MCP brings real-time security checks to AI-generated code, helping developers catch risky dependencies before they enter the codebase.