ESLint can now lint HTML using the html-eslint language plugin

In 2024, ESLint announced its plan to become a language-agnostic linter that is capable of linting languages other than JavaScript. Since then, we’ve seen official support added for JSON and Markdown, and most recently, CSS. Today, I’m excited to share that html-eslint now provides an ESLint language plugin for linting HTML.

Linting HTML with html-eslint

The @html-eslint/eslint-plugin package provides support for linting HTML code inside .html files. To get started, install it from npm:

npm install -D @html-eslint/eslint-plugin

Then update your configuration file:

import { defineConfig } from "eslint/config";
import html from "@html-eslint/eslint-plugin";

export default defineConfig([
    // lint html files
    {
        files: ["**/*.html"],
        plugins: {
            html,
        },
        language: "html/html",
        rules: {
            "html/no-duplicate-class": "error",
        }
    }
]);

The plugin includes a growing list of rules covering best practices, code style, search engine optimization (SEO), and accessibility. Have an idea for a rule? Open an issue.

HTML AST Support in Code Explorer

We’re also happy to share that Code Explorer now supports html-eslint, allowing you to view and explore the HTML AST directly in your browser. You can refer to this to implement custom rules for HTML.

Template engine syntax support

Rather than using plain HTML, some projects use template engines like Handlebars, which introduce non-standard syntax such as {{variable}}.

html-eslint is designed to offer support for custom syntax patterns used in popular template engines. This allows users to configure html-eslint to tolerate these syntaxes. Here’s an example:

import { defineConfig } from "eslint/config";
import html from "@html-eslint/eslint-plugin";

export default defineConfig([
    // lint html files
    {
        files: ["**/*.html"],
        plugins: {
            html,
        },
        language: "html/html",
        languageOptions: {
            // This tells the parser to treat {{ ... }} as template syntax,
            // so it won’t try to parse contents inside as regular HTML
            templateEngineSyntax: {
                "{{": "}}",
            },
        },
        rules: {
            "html/require-img-alt": "error"
        }
    }
]);

Linting HTML code inside JavaScript template literals

In addition to standalone HTML files, html-eslint also supports linting HTML inside JavaScript and TypeScript template literals, such as:

html`<div class="box">${content}</div>`;

// or

const code = /* html */ `<img class="image" src=${src}/>`;

This is especially useful when working with libraries like Lit, where HTML is commonly written inside tagged template literals.

To enable this, you don’t need to set a language. Just apply html-eslint rules to your JavaScript or TypeScript files, and the plugin will detect and lint HTML within template literals.

import { defineConfig } from "eslint/config";
import html from "@html-eslint/eslint-plugin";

export default defineConfig([
    {
        files: ["**/*.js", "**/*.ts"],
        plugins: {
            html,
        },
        rules: {
            "html/require-img-alt": "error",
        },
    },
]);

Conclusion

With language plugin support, html-eslint now works seamlessly with ESLint’s new architecture. Whether you’re maintaining static HTML, building components in Lit or web frameworks, or embedding HTML inside JavaScript, html-eslint now integrates cleanly with your ESLint configuration.

We hope you find the new HTML linting features helpful and look forward to seeing how you incorporate them into your projects. We’d love to hear your thoughts, feature suggestions, or ideas for new rules. Thank you for your support and interest in the html-eslint project!