Linter Rule: Disallow unknown HTML tags

Rule: html-no-unknown-tag

Description

Disallow HTML elements that are not part of the HTML Living Standard. Non-standard tags like <hello> or <foo> are almost always typos or mistakes and should be flagged.

Rationale

Browsers will render unknown HTML elements as inline elements with no special behavior, creating an HTMLUnknownElement instance. This is rarely intentional and usually indicates a typo or a misunderstanding of the available HTML elements.

Custom elements (tags containing a hyphen, like <turbo-frame> or <my-component>) are valid per the Web Components specification and are always allowed.

This rule also checks Action View tag helpers like <%= tag.hello %>, since the parser resolves these to their corresponding HTML elements. Note that tag.my_component is automatically translated to <my-component> by Rails and will not trigger this rule.

Examples

✅ Good

<div></div>
<span></span>
<section></section>
<img src="logo.png" alt="Logo">

<turbo-frame id="messages"></turbo-frame>
<my-component></my-component>

<Button></Button>
Closing tag name `</Button>` should be lowercase. Use `</button>` instead. (html-tag-name-lowercase)
Opening tag name `<Button>` should be lowercase. Use `<button>` instead. (html-tag-name-lowercase)
<UI::Button></UI::Button>
Closing tag name `</UI::Button>` should be lowercase. Use `</ui::button>` instead. (html-tag-name-lowercase)
Opening tag name `<UI::Button>` should be lowercase. Use `<ui::button>` instead. (html-tag-name-lowercase)

<svg viewBox="0 0 24 24">
  <path d="M0 0h24v24H0z"></path>
  <circle cx="12" cy="12" r="10"></circle>
</svg>

<math>
  <mrow><mi>x</mi><mo>=</mo><mn>1</mn></mrow>
</math>

<%= tag.div do %>content<% end %>
<%= tag.my_component do %>content<% end %>

🚫 Bad

<hello></hello>
Unknown HTML tag `<hello>`. This is not a standard HTML element. (html-no-unknown-tag)

<foo></foo>
Unknown HTML tag `<foo>`. This is not a standard HTML element. (html-no-unknown-tag)

<my_component></my_component>
Unknown HTML tag `<my_component>`. This is not a standard HTML element. Did you mean `<my-component>`? Custom elements must contain a hyphen. (html-no-unknown-tag)

<%= tag.hello do %>content<% end %>
Unknown HTML tag `<hello>`. This is not a standard HTML element. (html-no-unknown-tag)

References

• HTML Living Standard: Elements
• MDN: HTMLUnknownElement
• HTML Living Standard: Valid custom element name