Development of Web Components (Custom Elements) for a Site
Integrating complex UI logic into a project without frameworks is a headache. We often encounter the task of creating a reusable element that works equally well in WordPress, Laravel Blade, and static HTML. The solution is Web Components — a set of native browser APIs that allow you to develop custom HTML elements with encapsulated logic and styles. No dependencies on React, Vue, or jQuery. The components live in any HTML context.
Three constituents: Custom Elements API (registering a new tag), Shadow DOM (style encapsulation), HTML Templates (templating). They are used independently or together. Our team's experience is 5+ years of native development, with over 10 projects using Web Components. We guarantee cross-browser compatibility and performance.
Main Problems When Integrating Custom Elements
The first problem is style conflicts. Without Shadow DOM, inline styles can be overridden by global CSS rules. The second is lack of reactivity: unlike frameworks, native elements do not update automatically when attributes change. The third is testing complexity: it requires an environment with Custom Elements support. We solve these problems through thoughtful architecture and the use of TypeScript.
Advantages of Web Components
The main advantage is independence from frameworks. A component written once works in any project: React, Vue, Angular, Svelte, plain HTML. This reduces development time by 30% and simplifies maintenance. Additionally, Web Components require no bundler — their size is zero, unlike React components that need ~40 KB of library. For an old project on jQuery, this is an ideal way to add modern functionality without migrating the entire stack.
How to Create a Custom Element from Scratch?
The process consists of five steps:
- Design the component API — determine attributes, events, and public methods.
- Write a class inheriting from HTMLElement.
- Implement lifecycle methods (connectedCallback, attributeChangedCallback, etc.).
- Register the element via customElements.define().
- Test in several browsers.
Here is a typical example — a notification component:
class ToastNotification extends HTMLElement {
private shadow: ShadowRoot
private messageEl: HTMLElement | null = null
static get observedAttributes() {
return ['type', 'message', 'duration']
}
constructor() {
super()
this.shadow = this.attachShadow({ mode: 'open' })
}
connectedCallback() {
this.render()
const duration = parseInt(this.getAttribute('duration') || '3000')
if (duration > 0) {
setTimeout(() => this.dismiss(), duration)
}
}
disconnectedCallback() {
this.messageEl?.removeEventListener('click', this.dismiss)
}
attributeChangedCallback(name: string, oldVal: string, newVal: string) {
if (oldVal !== newVal && this.isConnected) {
this.render()
}
}
private render() {
const type = this.getAttribute('type') || 'info'
const message = this.getAttribute('message') || ''
this.shadow.innerHTML = `
<style>
:host {
display: block;
font-family: inherit;
}
.toast {
padding: 12px 20px;
border-radius: 8px;
font-size: 14px;
line-height: 1.4;
cursor: pointer;
animation: slide-in 0.3s ease;
}
.toast--info { background: #1a1a2e; color: #7eb8f7; border: 1px solid #2a4a7f; }
.toast--success { background: #0d2e1a; color: #5cb85c; border: 1px solid #1a5e30; }
.toast--error { background: #2e0d0d; color: #e74c3c; border: 1px solid #7f1a1a; }
@keyframes slide-in {
from { transform: translateY(-10px); opacity: 0; }
to { transform: translateY(0); opacity: 1; }
}
</style>
<div class="toast toast--${type}" part="toast">
${message}
</div>
`
this.messageEl = this.shadow.querySelector('.toast')
this.messageEl?.addEventListener('click', this.dismiss)
}
private dismiss = () => {
this.dispatchEvent(new CustomEvent('toast-dismiss', {
bubbles: true,
composed: true,
}))
this.remove()
}
show(message: string, type = 'info') {
this.setAttribute('message', message)
this.setAttribute('type', type)
if (!this.isConnected) {
document.body.appendChild(this)
}
}
}
customElements.define('toast-notification', ToastNotification)
It can be used via HTML as well as via JS.
Lifecycle and TypeScript
Custom Elements provide four lifecycle methods: constructor, connectedCallback, disconnectedCallback, attributeChangedCallback. For correct integration with TypeScript, you need to declare types in HTMLElementTagNameMap:
declare global {
interface HTMLElementTagNameMap {
'toast-notification': ToastNotification
}
}
Typing custom elements is an important step for creating business components with autocompletion in the IDE.
| Method | When called | What to do |
|---|---|---|
| constructor | When element is created | State initialization, Shadow DOM creation |
| connectedCallback | When added to DOM | Set up handlers, load data |
| disconnectedCallback | When removed from DOM | Clean up handlers, timers |
| attributeChangedCallback | When a tracked attribute changes | Update view |
When is Shadow DOM Not Needed?
Shadow DOM adds isolation but also complexity. For simple elements (e.g., a counter or collapsible list), Light DOM is sufficient — styles inherit from the parent, the code is simpler. Example of an accordion:
class AccordionItem extends HTMLElement {
private header!: HTMLElement
private content!: HTMLElement
private isOpen = false
connectedCallback() {
this.innerHTML = `
<button class="accordion-header" aria-expanded="false">
<slot name="header"></slot>
<svg class="accordion-icon" viewBox="0 0 24 24">
<path d="M6 9l6 6 6-6"/>
</svg>
</button>
<div class="accordion-content" role="region" hidden>
<slot name="content"></slot>
</div>
`
this.header = this.querySelector('.accordion-header')!
this.content = this.querySelector('.accordion-content')!
this.header.addEventListener('click', this.toggle)
}
private toggle = () => {
this.isOpen = !this.isOpen
this.header.setAttribute('aria-expanded', String(this.isOpen))
this.content.hidden = !this.isOpen
}
disconnectedCallback() {
this.header?.removeEventListener('click', this.toggle)
}
}
customElements.define('accordion-item', AccordionItem)
Comparison of Approaches
| Parameter | Shadow DOM | Light DOM |
|---|---|---|
| Style encapsulation | Full | None |
| Complexity | Higher | Lower |
| Performance | Same | Same |
| Suitable for | Libraries, complex widgets | Simple interactive elements |
| Approach | Time for first component | Reusability | Dependencies |
|---|---|---|---|
| Web Components | 4-8 hours | 100% in any project | None |
| React component | 2-4 hours | only in React | 40KB |
| Vue component | 2-4 hours | only in Vue | 30KB |
What’s Included in the Work?
- Component API design
- Implementation in TypeScript with full lifecycle
- Writing type declarations
- Integration with the existing project
- Documentation on usage and customization
- One month of support after delivery
Timeline and Cost
One simple component without Shadow DOM — from 4 to 8 hours. A complex component with animations, tests, and TypeScript — 1–3 days. A library of 5–10 components — 1–2 weeks. The cost is calculated individually for your project. Contact us for a free consultation — we will evaluate the implementation and offer an optimal solution.
On one project for a major bank, we developed a library of 8 custom elements (accordion, tabs, notifications, dropdown, modal window, paginator, product card, slider) to replace jQuery plugins. As a result, the page size decreased by 200 KB, and loading speed increased by 15%. Moreover, the components were used both in WordPress and in the React admin panel without changes. Such resource savings are a direct consequence of the absence of dependencies and the lightness of native elements.
Order custom Web Components development — get reliable, independent elements for any site. Get a consultation — we will answer all questions and help you choose the optimal approach.