html-loader

Exports HTML as string. HTML is minimized when the compiler demands.

Getting Started

To begin, you'll need to install html-loader:

npm install --save-dev 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',
      },
    ],
  },
};

By default every loadable attributes (for example - <img src="image.png">) is imported (const img = require('./image.png') or import img from "./image.png"").
You may need to specify loaders for images in your configuration (recommended file-loader or url-loader).

Options, Name, Type, Default, Description, :-------------------------------:, :-----------------:, :-------------------------------------------------------------------------------------------------------------------:, :---------------------------------------, attributes, {Boolean\/Array}, [':srcset', 'img:src', 'audio:src', 'video:src', 'track:src', 'embed:src', 'source:src','input:src', 'object:data'], Enables/Disables attributes handling, root, {String}, undefiend, Allow to handle root-relative attributes, interpolate, {Boolean}, false, Allow to use expressions in HTML syntax, minimize, {Boolean\, Object}, true in production mode, otherwise false, Tell html-loader to minimize HTML, esModule, {Boolean}, false, Use ES modules syntax, ### attributes

Type: Boolean, Array
Default: [':srcset', 'img:src', 'audio:src', 'video:src', 'track:src', 'embed:src', 'source:src', 'input:src', 'object:data']

Boolean

The true value enables processing of all default elements and attributes, the false disable processing of all attributes.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          // Disables tags and attributes processing
          attributes: false,
        },
      },
    ],
  },
};

Array

Allows you to specify which tags and attributes to process.
Pass an array of <tag>:<attribute> or :<attribute> combinations.
You can specify which tag-attribute combination should be processed by this loader via the query parameter attributes, for example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          attributes: [':data-src', 'custom-elements:data-src'],
        },
      },
    ],
  },
};

To completely disable tag-attribute processing (for instance, if you're handling image loading on the client side) you can pass set false value.

root

Type: String
Default: undefined

For urls that start with a /, the default behavior is to not translate them.
If a root query parameter is set, however, it will be prepended to the url and then translated.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          root: './file.html',
        },
      },
    ],
  },
};

interpolate

Type: Boolean, String
Default: false

Allow to use expressions in HTML syntax.
You can use interpolate flag to enable interpolation syntax for ES6 template strings, like so:

require('html-loader?interpolate!./file.html');

<img src="${require(`./images/gallery.png`).default}" />

<div>${require('./components/gallery.html').default}</div>

⚠ By default file-loader or url-loader use ES module syntax so you need use the default property.
You should not use the default property if you setup the esModule option to false value for file-loader or url-loader.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          interpolate: true,
        },
      },
    ],
  },
};

minimize

Type: Boolean, Object
Default: true in production mode, otherwise false

Tell html-loader to minimize HTML.

Boolean

The enabled rules for minimizing by default are the following ones:

• collapseWhitespace
• conservativeCollapse
• keepClosingSlash
• minifyCSS
• minifyJS
• removeAttributeQuotes
• removeComments
• removeScriptTypeAttributes
• removeStyleTypeAttributes
• useShortDoctype

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          minimize: true,
        },
      },
    ],
  },
};

Object

webpack.config.js

See html-minifier's documentation for more information on the available options.

The rules can be disabled 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,
          },
        },
      },
    ],
  },
};

esModule

Type: Boolean
Default: false

By default, html-loader generates JS modules that use the CommonJS 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 ES module syntax using:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          esModule: true,
        },
      },
    ],
  },
};

Examples

CDN

webpack.config.js

module.exports = {
  module: {
    rules: [
      { test: /\.jpg$/, loader: 'file-loader' },
      { test: /\.png$/, loader: 'url-loader' },
    ],
  },
  output: {
    publicPath: 'http://cdn.example.com/[hash]/',
  },
};

<!-- file.html -->
<img src="image.png" data-src="image2x.png" />

require('html-loader!./file.html');

// => '<img src="http://cdn.example.com/49eba9f/a992ca.png" data-src="image2x.png">'

require('html-loader?attributes[]=img:data-src!./file.html');

// => '<img src="image.png" data-src="data:image/png;base64,..." >'

require('html-loader?attributes[]=img:src&attributes[]=img:data-src!./file.html');

// => '<img src="http://cdn.example.com/49eba9f/a992ca.png" data-src="data:image/png;base64,..." >'

require('html-loader?-attributes!./file.html');

// => '<img src="image.jpg"  data-src="image2x.png" >'

'<img src=http://cdn.example.com/49eba9f/a9f92ca.jpg
data-src=data:image/png;base64,...>'

'Root-relative' URLs

With the same configuration as above:

<!-- file.html -->
<img src="/image.jpg" />

require('html-loader!./file.html');

// => '<img src="/image.jpg">'

require('html-loader?root=.!./file.html');

// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg">'

Export into HTML files

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 3 loaders:

• file-loader
• extract-loader
• html-loader

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 file loader
will write the .html file for you. Example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        use: ['file-loader?name=[name].[ext]', 'extract-loader', 'html-loader'],
      },
    ],
  },
};

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT