\n\n[![npm][npm]][npm-url]\n[![node][node]][node-url]\n[![tests][tests]][tests-url]\n[![coverage][cover]][cover-url]\n[![discussion][discussion]][discussion-url]\n[![size][size]][size-url]\n\n# html-loader\n\nExports HTML as string. HTML is minimized when the compiler demands.\n\n## Getting Started\n\nTo begin, you'll need to install `html-loader`:\n\n```console\nnpm install --save-dev html-loader\n```\n\nor\n\n```console\nyarn add -D html-loader\n```\n\nor\n\n```console\npnpm add -D html-loader\n```\n\nThen add the plugin to your `webpack` config. For example:\n\n**file.js**\n\n```js\nimport html from \"./file.html\";\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n },\n ],\n },\n};\n```\n\n## Options\n\n- **[`sources`](#sources)**\n- **[`preprocessor`](#preprocessor)**\n- **[`postprocessor`](#postprocessor)**\n- **[`minimize`](#minimize)**\n- **[`esModule`](#esmodule)**\n\n### `sources`\n\nType:\n\n```ts\ntype sources =\n | boolean\n | {\n list?: Array<{\n tag?: string;\n attribute?: string;\n type?: string;\n filter?: (\n tag: string,\n attribute: string,\n attributes: string,\n resourcePath: string,\n ) => boolean;\n }>;\n urlFilter?: (\n attribute: string,\n value: string,\n resourcePath: string,\n ) => boolean;\n scriptingEnabled?: boolean;\n };\n```\n\nDefault: `true`\n\nBy default every loadable attribute (for example - ``) is imported (`const img = require('./image.png')` or `new URL(\"./image.png\", import.meta.url)`).\nYou may need to specify loaders for images in your configuration (recommended [`asset modules`](https://webpack.js.org/guides/asset-modules/)).\n\nSupported tags and attributes:\n\n- the `src` attribute of the `audio` tag\n- the `src` attribute of the `embed` tag\n- the `src` attribute of the `img` tag\n- the `srcset` attribute of the `img` tag\n- the `src` attribute of the `input` tag\n- the `data` attribute of the `object` tag\n- the `src` attribute of the `script` tag\n- the `href` attribute of the `script` tag\n- the `xlink:href` attribute of the `script` tag\n- the `src` attribute of the `source` tag\n- the `srcset` attribute of the `source` tag\n- the `src` attribute of the `track` tag\n- the `poster` attribute of the `video` tag\n- the `src` attribute of the `video` tag\n- the `xlink:href` attribute of the `image` tag\n- the `href` attribute of the `image` tag\n- the `xlink:href` attribute of the `use` tag\n- the `href` attribute of the `use` tag\n- the `href` 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`, `layoutimage`\n- the `imagesrcset` 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`\n- the `content` 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`, `layoutimage`\n- the `icon-uri` value component in `content` attribute of the `meta` tag when the `name` attribute is `msapplication-task`\n\n#### `boolean`\n\nThe `true` value enables the processing of all default elements and attributes, the `false` value disables the processing of all attributes.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n // Disables attributes processing\n sources: false,\n },\n },\n ],\n },\n};\n```\n\n#### `object`\n\nAllows you to specify which tags and attributes to process, filter them, filter urls and process sources starting with `/`.\n\nFor example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n // All default supported tags and attributes\n \"...\",\n {\n tag: \"img\",\n attribute: \"data-src\",\n type: \"src\",\n },\n {\n tag: \"img\",\n attribute: \"data-srcset\",\n type: \"srcset\",\n },\n ],\n urlFilter: (attribute, value, resourcePath) => {\n // The `attribute` argument contains a name of the HTML attribute.\n // The `value` argument contains a value of the HTML attribute.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n if (/example\\.pdf$/.test(value)) {\n return false;\n }\n\n return true;\n },\n },\n },\n },\n ],\n },\n};\n```\n\n#### `list`\n\nType:\n\n```ts\ntype list = Array<{\n tag?: string;\n attribute?: string;\n type?: string;\n filter?: (\n tag: string,\n attribute: string,\n attributes: string,\n resourcePath: string,\n ) => boolean;\n}>;\n```\n\nDefault: [supported tags and attributes](#sources).\n\nAllows to setup which tags and attributes to process and how, as well as the ability to filter some of them.\n\nUsing `...` syntax allows you to extend [default supported tags and attributes](#sources).\n\nFor example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n // All default supported tags and attributes\n \"...\",\n {\n tag: \"img\",\n attribute: \"data-src\",\n type: \"src\",\n },\n {\n tag: \"img\",\n attribute: \"data-srcset\",\n type: \"srcset\",\n },\n {\n // Tag name\n tag: \"link\",\n // Attribute name\n attribute: \"href\",\n // Type of processing, can be `src` or `scrset`\n type: \"src\",\n // Allow to filter some attributes\n filter: (tag, attribute, attributes, resourcePath) => {\n // The `tag` argument contains a name of the HTML tag.\n // The `attribute` argument contains a name of the HTML attribute.\n // The `attributes` argument contains all attributes of the tag.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n if (/my-html\\.html$/.test(resourcePath)) {\n return false;\n }\n\n if (!/stylesheet/i.test(attributes.rel)) {\n return false;\n }\n\n if (\n attributes.type &&\n attributes.type.trim().toLowerCase() !== \"text/css\"\n ) {\n return false;\n }\n\n return true;\n },\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\nIf the tag name is not specified it will process all the tags.\n\n> You can use your custom filter to specify html elements to be processed.\n\nFor example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n {\n // Attribute name\n attribute: \"src\",\n // Type of processing, can be `src` or `scrset`\n type: \"src\",\n // Allow to filter some attributes (optional)\n filter: (tag, attribute, attributes, resourcePath) => {\n // The `tag` argument contains a name of the HTML tag.\n // The `attribute` argument contains a name of the HTML attribute.\n // The `attributes` argument contains all attributes of the tag.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n // choose all HTML tags except img tag\n return tag.toLowerCase() !== \"img\";\n },\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\nFilter can also be used to extend the supported elements and attributes.\n\nFor example, filter can help process meta tags that reference assets:\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n {\n tag: \"meta\",\n attribute: \"content\",\n type: \"src\",\n filter: (tag, attribute, attributes, resourcePath) => {\n if (\n attributes.value === \"og:image\" ||\n attributes.name === \"twitter:image\"\n ) {\n return true;\n }\n\n return false;\n },\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\n> [!NOTE]\n>\n> source with a `tag` option takes precedence over source without.\n\nFilter can be used to disable default sources.\n\nFor example:\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n \"...\",\n {\n tag: \"img\",\n attribute: \"src\",\n type: \"src\",\n filter: () => false,\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\n#### `urlFilter`\n\nType:\n\n```ts\ntype urlFilter = (\n attribute: string,\n value: string,\n resourcePath: string,\n) => boolean;\n```\n\nDefault: `undefined`\n\nAllow to filter urls. All filtered urls will not be resolved (left in the code as they were written).\nNon-requestable sources (for example ``) are not handled by default.\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n urlFilter: (attribute, value, resourcePath) => {\n // The `attribute` argument contains a name of the HTML attribute.\n // The `value` argument contains a value of the HTML attribute.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n if (/example\\.pdf$/.test(value)) {\n return false;\n }\n\n return true;\n },\n },\n },\n },\n ],\n },\n};\n```\n\n#### `scriptingEnabled`\n\nType:\n\n```ts\ntype scriptingEnabled = boolean;\n```\n\nDefault: `true`\n\nBy default, the parser in `html-loader` interprets content inside `
![\"html-loader\"](\"https://www.w3.org/html/logo/downloads/HTML5_Logo.svg\"){kind=logo}
\n \n ![\"webpack\"](\"https://webpack.js.org/assets/icon-square-big.svg\"){kind=icon}
\n \n![](\"image.png\")
`) is imported (`const img = require('./image.png')` or `new URL(\"./image.png\", import.meta.url)`).\nYou may need to specify loaders for images in your configuration (recommended [`asset modules`](https://webpack.js.org/guides/asset-modules/)).\n\nSupported tags and attributes:\n\n- the `src` attribute of the `audio` tag\n- the `src` attribute of the `embed` tag\n- the `src` attribute of the `img` tag\n- the `srcset` attribute of the `img` tag\n- the `src` attribute of the `input` tag\n- the `data` attribute of the `object` tag\n- the `src` attribute of the `script` tag\n- the `href` attribute of the `script` tag\n- the `xlink:href` attribute of the `script` tag\n- the `src` attribute of the `source` tag\n- the `srcset` attribute of the `source` tag\n- the `src` attribute of the `track` tag\n- the `poster` attribute of the `video` tag\n- the `src` attribute of the `video` tag\n- the `xlink:href` attribute of the `image` tag\n- the `href` attribute of the `image` tag\n- the `xlink:href` attribute of the `use` tag\n- the `href` attribute of the `use` tag\n- the `href` 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`, `layoutimage`\n- the `imagesrcset` 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`\n- the `content` 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`, `layoutimage`\n- the `icon-uri` value component in `content` attribute of the `meta` tag when the `name` attribute is `msapplication-task`\n\n#### `boolean`\n\nThe `true` value enables the processing of all default elements and attributes, the `false` value disables the processing of all attributes.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n // Disables attributes processing\n sources: false,\n },\n },\n ],\n },\n};\n```\n\n#### `object`\n\nAllows you to specify which tags and attributes to process, filter them, filter urls and process sources starting with `/`.\n\nFor example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n // All default supported tags and attributes\n \"...\",\n {\n tag: \"img\",\n attribute: \"data-src\",\n type: \"src\",\n },\n {\n tag: \"img\",\n attribute: \"data-srcset\",\n type: \"srcset\",\n },\n ],\n urlFilter: (attribute, value, resourcePath) => {\n // The `attribute` argument contains a name of the HTML attribute.\n // The `value` argument contains a value of the HTML attribute.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n if (/example\\.pdf$/.test(value)) {\n return false;\n }\n\n return true;\n },\n },\n },\n },\n ],\n },\n};\n```\n\n#### `list`\n\nType:\n\n```ts\ntype list = Array<{\n tag?: string;\n attribute?: string;\n type?: string;\n filter?: (\n tag: string,\n attribute: string,\n attributes: string,\n resourcePath: string,\n ) => boolean;\n}>;\n```\n\nDefault: [supported tags and attributes](#sources).\n\nAllows to setup which tags and attributes to process and how, as well as the ability to filter some of them.\n\nUsing `...` syntax allows you to extend [default supported tags and attributes](#sources).\n\nFor example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n // All default supported tags and attributes\n \"...\",\n {\n tag: \"img\",\n attribute: \"data-src\",\n type: \"src\",\n },\n {\n tag: \"img\",\n attribute: \"data-srcset\",\n type: \"srcset\",\n },\n {\n // Tag name\n tag: \"link\",\n // Attribute name\n attribute: \"href\",\n // Type of processing, can be `src` or `scrset`\n type: \"src\",\n // Allow to filter some attributes\n filter: (tag, attribute, attributes, resourcePath) => {\n // The `tag` argument contains a name of the HTML tag.\n // The `attribute` argument contains a name of the HTML attribute.\n // The `attributes` argument contains all attributes of the tag.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n if (/my-html\\.html$/.test(resourcePath)) {\n return false;\n }\n\n if (!/stylesheet/i.test(attributes.rel)) {\n return false;\n }\n\n if (\n attributes.type &&\n attributes.type.trim().toLowerCase() !== \"text/css\"\n ) {\n return false;\n }\n\n return true;\n },\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\nIf the tag name is not specified it will process all the tags.\n\n> You can use your custom filter to specify html elements to be processed.\n\nFor example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n {\n // Attribute name\n attribute: \"src\",\n // Type of processing, can be `src` or `scrset`\n type: \"src\",\n // Allow to filter some attributes (optional)\n filter: (tag, attribute, attributes, resourcePath) => {\n // The `tag` argument contains a name of the HTML tag.\n // The `attribute` argument contains a name of the HTML attribute.\n // The `attributes` argument contains all attributes of the tag.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n // choose all HTML tags except img tag\n return tag.toLowerCase() !== \"img\";\n },\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\nFilter can also be used to extend the supported elements and attributes.\n\nFor example, filter can help process meta tags that reference assets:\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n {\n tag: \"meta\",\n attribute: \"content\",\n type: \"src\",\n filter: (tag, attribute, attributes, resourcePath) => {\n if (\n attributes.value === \"og:image\" ||\n attributes.name === \"twitter:image\"\n ) {\n return true;\n }\n\n return false;\n },\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\n> [!NOTE]\n>\n> source with a `tag` option takes precedence over source without.\n\nFilter can be used to disable default sources.\n\nFor example:\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n list: [\n \"...\",\n {\n tag: \"img\",\n attribute: \"src\",\n type: \"src\",\n filter: () => false,\n },\n ],\n },\n },\n },\n ],\n },\n};\n```\n\n#### `urlFilter`\n\nType:\n\n```ts\ntype urlFilter = (\n attribute: string,\n value: string,\n resourcePath: string,\n) => boolean;\n```\n\nDefault: `undefined`\n\nAllow to filter urls. All filtered urls will not be resolved (left in the code as they were written).\nNon-requestable sources (for example ``) are not handled by default.\n\n```js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.html$/i,\n loader: \"html-loader\",\n options: {\n sources: {\n urlFilter: (attribute, value, resourcePath) => {\n // The `attribute` argument contains a name of the HTML attribute.\n // The `value` argument contains a value of the HTML attribute.\n // The `resourcePath` argument contains a path to the loaded HTML file.\n\n if (/example\\.pdf$/.test(value)) {\n return false;\n }\n\n return true;\n },\n },\n },\n },\n ],\n },\n};\n```\n\n#### `scriptingEnabled`\n\nType:\n\n```ts\ntype scriptingEnabled = boolean;\n```\n\nDefault: `true`\n\nBy default, the parser in `html-loader` interprets content inside `![](\"/image.jpg\")
![](\"image2x.png\")
![](\"image.jpg\")
![](\"http://cdn.example.com/49eba9f/a992ca.jpg\")