Course contentsShow
← Web Development
Lesson 2447 of 2,98244. Web ComponentsFree lesson

Custom Element Naming Requirements

Understanding the mandatory hyphen requirement and naming conventions for valid custom element tags.

Custom Element Naming Requirements

What you'll learn: You'll understand why custom elements must contain a hyphen and follow specific naming rules to be valid.


Why the Hyphen is Mandatory

When you register a custom element, its tag name must include at least one hyphen (the dash character: -). This isn't arbitrary—it's a collision-prevention mechanism built into the Web Components spec.

Think of it like namespacing in programming: the hyphen ensures your custom elements will never conflict with current or future HTML elements. Native HTML tags (like button, input, header) never contain hyphens, so my-button is guaranteed safe while mybutton could theoretically collide with a future HTML standard element.

Valid Naming Rules

Your custom element name must:

  1. Contain at least one hyphen: user-profile ✓, userprofile ✗
  2. Start with a lowercase ASCII letter (a-z): my-widget ✓, 2-widget ✗, My-widget ✗
  3. Not include uppercase letters: my-component ✓, myComponent ✗
  4. Avoid reserved names that could conflict with HTML parsing (e.g., names containing certain special characters)

Examples

Valid:
- my-element
- user-profile-card
- x-button
- super-mega-awesome-widget

Invalid:
- myelement (no hyphen)
- MyElement (no hyphen, uppercase)
- my-Element (uppercase letter)
- 123-widget (doesn't start with letter)

The hyphen requirement also improves readability—it clearly signals "this is custom, not native HTML."

Key Takeaway: Custom element names must contain at least one hyphen and use only lowercase letters to prevent naming collisions with current and future HTML elements.