html-loader

What is html-loader?

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.

What are html-loader's main functionalities?

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 } }] }] } }

Other packages similar to html-loader

raw-loader

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.

handlebars-loader

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.

pug-loader

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).

README

HTML Loader

Exports HTML as `{String}` or template `{Function}`

Install

npm i -D html-loader

Usage

By default all assets (<img src="./image.png">) are transpiled to their own module requests (import HTML__URL__O from './image.png') to be correctly handled by webpack as an ES Module

⚠️ You need to specify additional loaders for your assets (e.g images) separately in your webpack.config.js, like the file-loader or url-loader, to handle these requests

webpack.config.js

{
  test: /\.html$/,
  use: {
    loader: 'html-loader',
    options: {}
  }
}

Caching

If your application includes many HTML Components or certain HTML Components are of significant size, we highly recommend to use the cache-loader for persistent caching (faster initial builds)

webpack.config.js

{
  test: /\.html$/,
  use: [
    'cache-loader',
    {
      loader: 'html-loader',
      options: {}
    }
  ]
}

Options

Name	Type	Default	Description
url	{Boolean}	true	Enable/Disable HTML Assets (<img src="./file.png">)
import	{Boolean}	true	Enable/Disable HTML Imports (<import src="./file.html">)
template	{Boolean|String}	false	Export HTML as a template {Function}. The template placeholder defaults to <div>${ _.x }</div> (_)
minimize	{Boolean}	false	Enable/Disable HTML Minification

url

It's possible to completely disable or filter certain URL's from resolving in case these assets shouldn't be handled by webpack. Protocol URL's like (<img src="https://cnd.domain.com/image.png">) are ignored by default

{Boolean}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    url: false
  }
}

{RegExp}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    url: /filter/
  }
}

{Function}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    url (url) {
      return /filter/.test(url)
    }
  }
}

import

import.html

<div class="import">Import</div>

file.html

<div>
  <import src="./import.html"></import>
</div>

{Boolean}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    import: false
  }
}

{RegExp}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    import: /filter/
  }
}

{Function}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    import (url) {
      return /filter/.test(url)
    }
  }
}

template

When set to true the loader will export a template {Function} instead of a {String}. The locals param is configurable and defaults to _

{Boolean}

file.html

<div>
  <p>${ _.txt }</p>
</div>

file.js

import template from './file.html'

const html = template({ txt: 'Hello World!' })

document.body.innerHTML = html

webpack.config.js

{
  loader: 'html-loader',
  options: {
    template: true
  }
}

{String}

Sets a custom placeholder for your template {Function}

file.html

<div>
  <p>${ $.txt }</p>
</div>

file.js

import template from './file.html'

const html = template({ txt: 'Hello World!' })

document.body.innerHTML = html

webpack.config.js

{
  loader: 'html-loader',
  options: {
    template: '$'
  }
}

minimize

{Boolean}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    minimize: true
  }
}

{Object}

Set custom options for minification

webpack.config.js

{
  loader: 'html-loader',
  options: {
    minimize: {...options}
  }
}

Examples

HMR

component.js

import template from './component.html';

const component = document.createElement('div')

component.innerHTML = template({ hello: 'Hello World!' })

document.body.appendChild(component);

// HMR Interface
if (module.hot) {
  // Capture hot update
  module.hot.accept('./component.html', () => {
    // Replace old content with the hot loaded one
    component.innerHTML = template({ ...locals })
  })
}

npm Packages (Modules)

:information_source: Any key matching with resolve.mainFields is valid and should work. pkg.template is just used as an example here.

package.json

{
  "name": "@package",
  "version": "1.0.0",
  "template": "path/to/component.html"
}

webpack.config.js

const config = {
  module: {
    rules: [
      {
        test: /\.html$/,
        use: [ 'html-loader' ],
        resolve: {
          mainFields: [ 'template' ]
        }
      }
    ]
  }
}

module.exports = config

component.html

<import src="@package"></import>
<div>...<div>

component.js

import html from './file.html'

const el = document.createElement('div')

el.innerHTML = html

Maintainers

Hemanth	Joshua Wiens	Michael Ciniawsky	Imvetri
Andrei Crnković	Yuta Hiroto	Vesselin Petrunov	Gajus Kuizinas