# Web Component

Web Components are browser standards for defining reusable custom elements with lifecycle behavior and optional DOM and style encapsulation.

- Type: framework
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/web-component/>)

## What it means

Web Components are a set of platform capabilities centered on custom elements, shadow DOM, and HTML templates. A custom element defines a named HTML element and lifecycle callbacks; a shadow root can encapsulate internal markup and styling. The term describes standards-based components, not a single library or mandatory use of every capability.

## Why it matters

Web Components can cross framework boundaries and provide durable component contracts. Their encapsulation, styling, server rendering, forms, and accessibility behavior still require explicit design and testing.

## When to use it

Use them for shared elements that must work across multiple stacks, embedded products, or long-lived design-system primitives. A framework-native component may be simpler when reuse stays within one application and its data model.

## How it works

1. Define a valid custom-element name and a class with focused public behavior.
2. Register the class with the browser's custom element registry.
3. Use attributes, properties, methods, slots, and events as the component contract.
4. Optionally attach a shadow root and stamp template content for encapsulation.
5. Test lifecycle, styling hooks, keyboard behavior, accessible names, and framework integration.

## A practical example

A company publishes a date-range picker used by PHP pages and two JavaScript applications. Its custom element exposes properties and events, supports light-DOM labels, and documents CSS custom properties instead of leaking internal selectors.

## Where it breaks

Shadow boundaries complicate global styling, testing, and some accessibility inspection. Custom elements do not automatically provide good semantics, state management, server rendering, or small code, and wrapper work may be needed in frameworks.

## Common mistakes

- Calling any reusable UI component a Web Component.
- Using shadow DOM without stable styling and accessibility contracts.
- Encoding complex data only in string attributes.
- Recreating native controls without their keyboard and form behavior.

## Sources

1. [Web Components](<https://developer.mozilla.org/en-US/docs/Web/API/Web_components>) — MDN Web Docs · Official technical documentation
2. [HTML Standard: Custom Elements](<https://html.spec.whatwg.org/multipage/custom-elements.html>) — WHATWG · Living web standard

## Related topics

- [Component Library](<https://wiki.soroush.uk/topic/component-library/>)
- [Design System](<https://wiki.soroush.uk/topic/design-system/>)
- [Semantic HTML](<https://wiki.soroush.uk/topic/semantic-html/>)
