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:
- Contain at least one hyphen:
user-profile✓,userprofile✗ - Start with a lowercase ASCII letter (a-z):
my-widget✓,2-widget✗,My-widget✗ - Not include uppercase letters:
my-component✓,myComponent✗ - 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.