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)

ℹ️ 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