Ви вбудовуєте сторонній віджет на свій сайт і за годину виявляєте, що кнопки пофарбувалися в червоний, а скрипти почали конфліктувати з jQuery. Знайома ситуація? Ми пропонуємо рішення: кастомні HTML-елементи з Shadow DOM назавжди усувають цей головний біль. Клієнт вставляє три рядки коду й отримує працюючий віджет, ізольований від оточення хост-сайту. Сторонній віджет на чужому сайті — це чужа DOM, чужі стилі, потенційно конфліктуючі версії бібліотек. Custom Elements v1 вирішують цю проблему кардинально: жодних конфліктів CSS, жодних зламаних скриптів. Час завантаження такого віджета — 0.5–1.5 с (LCP), тоді як iframe-альтернатива потребуватиме 2–3 с. Це реалізація веб-компонентів, яка дає безшовну інтеграцію та повну ізоляцію.
Як кастомні HTML-елементи вирішують проблему конфліктів на сайті?
- Конфлікт стилів. Внутрішні стилі віджета можуть випадково перевизначити стилі сайту (наприклад,
button { background: red }). Shadow DOM гарантує ізоляцію в обидва боки. - Управління версіями. Віджет підключається одним скриптом з SRI-хешем. Клієнт не оновить віджет випадково — лише навмисно змінивши версію в URL.
- Кросбраузерність. Shadow DOM працює у всіх сучасних браузерах. Для IE11 підключаємо поліфіл. Тестуємо на реальних пристроях.
- SEO. На відміну від iframe, контент у Custom Element індексується пошуковиками. Це критично для віджетів відгуків, рейтингів, каталогів.
Що дає ізоляція Shadow DOM?
Shadow DOM — єдине надійне рішення. Ми створюємо <template> з інкапсульованими стилями та структурою. Ось мінімальний приклад:
<review-widget
data-product-id="SKU-12345"
data-theme="light"
data-locale="ru"
></review-widget>
Елемент сам завантажує дані через API та рендерить відгуки. Стилі ізольовані — жодні * { all: unset } хост-сторінки не зламають віджет.
Чому Custom Elements кращі за iframe для віджетів?
| Критерій | Custom Elements | iframe |
|---|---|---|
| Час завантаження (LCP) | < 1.5 с | ~3 с |
| SEO-індексація | Так | Ні |
| Адаптивність | Автоматична | Потрібна обгортка |
| Розмір скрипта | ~15 КБ (мініфікований) | > 50 КБ |
| Ізоляція стилів | Повна (Shadow DOM) | Повна (окремий документ) |
| Складність інтеграції | 3 рядки коду | Налаштування розмірів та postMessage |
| Розмір бандла після tree-shaking | ~8 КБ | ~30 КБ |
| Економія трафіку (на міс.) | до 2 000 $ | 0 $ |
Custom Elements в 2–3 рази швидші за iframe за часом завантаження і не приховують контент від пошуковиків. Економія трафіку — до 70% (до 2 000 $ на місяць).
| Браузер | Підтримка Custom Elements | Поліфіл |
|---|---|---|
| Chrome 54+ | Повна | Ні |
| Firefox 63+ | Повна | Ні |
| Safari 10.1+ | Повна | Ні |
| Edge 79+ | Повна | Ні |
| IE11 | Відсутня | Потрібен |
Як влаштований віджет зсередини
Архітектура включає три шари: Custom Element (реєструє тег, керує життєвим циклом), Shadow DOM (ізольовані стилі та розмітка), API-клієнт (завантажує дані з пагінацією). Нижче — повний код ReviewWidget:
// src/ReviewWidget.ts
const TEMPLATE = document.createElement('template');
TEMPLATE.innerHTML = `
<style>
:host {
display: block;
contain: content;
font-family: var(--rw-font, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
font-size: var(--rw-font-size, 14px);
color: var(--rw-text-color, #1a1a2e);
}
:host([hidden]) { display: none; }
.container {
border: 1px solid var(--rw-border-color, #e5e7eb);
border-radius: var(--rw-radius, 8px);
padding: 16px;
background: var(--rw-bg, #ffffff);
}
.rating {
display: flex;
align-items: center;
gap: 4px;
margin-bottom: 12px;
}
.star { color: #f59e0b; font-size: 18px; }
.star.empty { color: #d1d5db; }
.reviews-list { list-style: none; margin: 0; padding: 0; }
.review-item {
padding: 10px 0;
border-top: 1px solid #f3f4f6;
}
.review-author { font-weight: 600; font-size: 13px; }
.review-text { margin-top: 4px; line-height: 1.5; }
.load-more {
margin-top: 12px;
width: 100%;
padding: 8px;
background: var(--rw-accent, #3b82f6);
color: #fff;
border: none;
border-radius: 6px;
cursor: pointer;
font-size: 13px;
}
.load-more:hover { opacity: .9; }
.skeleton {
background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
background-size: 200% 100%;
animation: shimmer 1.5s infinite;
border-radius: 4px;
height: 14px;
margin: 6px 0;
}
@keyframes shimmer {
0% { background-position: 200% 0; }
100% { background-position: -200% 0; }
}
</style>
<div class="container">
<div class="rating" aria-label="Рейтинг товара"></div>
<ul class="reviews-list" role="list"></ul>
<button class="load-more" style="display:none">Показати ще</button>
</div>
`;
interface Review {
id: string;
author: string;
rating: number;
text: string;
date: string;
}
export class ReviewWidget extends HTMLElement {
static get observedAttributes() {
return ['data-product-id', 'data-theme', 'data-locale'];
}
private shadow: ShadowRoot;
private page = 1;
private allLoaded = false;
private apiBase = 'https://api.example.com/reviews';
constructor() {
super();
this.shadow = this.attachShadow({ mode: 'open' });
this.shadow.appendChild(TEMPLATE.content.cloneNode(true));
}
connectedCallback() {
this.applyTheme();
this.fetchReviews(true);
this.shadow.querySelector('.load-more')
?.addEventListener('click', () => this.fetchReviews(false));
}
attributeChangedCallback(name: string, old: string, next: string) {
if (old === next) return;
if (name === 'data-product-id') {
this.page = 1;
this.allLoaded = false;
this.fetchReviews(true);
}
if (name === 'data-theme') {
this.applyTheme();
}
}
private applyTheme() {
const theme = this.dataset.theme ?? 'light';
if (theme === 'dark') {
const container = this.shadow.querySelector<HTMLElement>('.container');
if (container) {
container.style.setProperty('--rw-bg', '#1f2937');
container.style.setProperty('--rw-text-color', '#f9fafb');
container.style.setProperty('--rw-border-color', '#374151');
}
}
}
private showSkeleton() {
const list = this.shadow.querySelector('.reviews-list')!;
list.innerHTML = Array(3).fill(
'<li><div class="skeleton"></div><div class="skeleton" style="width:70%"></div></li>'
).join('');
}
private async fetchReviews(reset: boolean) {
const productId = this.dataset.productId;
if (!productId) return;
if (reset) {
this.page = 1;
this.showSkeleton();
}
try {
const url = new URL(`${this.apiBase}/${productId}`);
url.searchParams.set('page', String(this.page));
url.searchParams.set('per_page', '5');
url.searchParams.set('locale', this.dataset.locale ?? 'ru');
const res = await fetch(url.toString(), {
headers: { 'X-Widget-Version': '2.1.0' },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data: { reviews: Review[]; total: number; avg_rating: number } =
await res.json();
this.renderRating(data.avg_rating, data.total);
this.renderReviews(data.reviews, reset);
this.allLoaded = data.reviews.length < 5;
const btn = this.shadow.querySelector<HTMLElement>('.load-more');
if (btn) btn.style.display = this.allLoaded ? 'none' : 'block';
this.page++;
// інформуємо хост-сторінку
this.dispatchEvent(new CustomEvent('reviews:loaded', {
detail: { total: data.total, avgRating: data.avg_rating },
bubbles: true,
composed: true,
}));
} catch (err) {
this.renderError();
}
}
private renderRating(avg: number, total: number) {
const ratingEl = this.shadow.querySelector('.rating')!;
const stars = Array.from({ length: 5 }, (_, i) =>
`<span class="star ${i < Math.round(avg) ? '' : 'empty'}">★</span>`
).join('');
ratingEl.innerHTML = `${stars} <span>${avg.toFixed(1)} (${total} відгуків)</span>`;
ratingEl.setAttribute('aria-label', `Рейтинг ${avg.toFixed(1)} з 5, ${total} відгуків`);
}
private renderReviews(reviews: Review[], reset: boolean) {
const list = this.shadow.querySelector('.reviews-list')!;
if (reset) list.innerHTML = '';
const locale = this.dataset.locale ?? 'ru';
const dateFormatter = new Intl.DateTimeFormat(locale, {
year: 'numeric', month: 'long', day: 'numeric',
});
reviews.forEach(r => {
const li = document.createElement('li');
li.className = 'review-item';
li.innerHTML = `
<div class="review-author">${r.author}
<time datetime="${r.date}" style="font-weight:400;color:#6b7280;margin-left:8px">
${dateFormatter.format(new Date(r.date))}
</time>
</div>
<div class="review-text">${r.text}</div>
`;
list.appendChild(li);
});
}
private renderError() {
this.shadow.querySelector('.reviews-list')!.innerHTML =
'<li style="color:#ef4444;padding:8px 0">Не вдалося завантажити відгуки</li>';
}
}
customElements.define('review-widget', ReviewWidget);
Скрипт завантаження підключається один раз і обробляє вже існуючі в DOM екземпляри:
// src/loader.ts
import { ReviewWidget } from './ReviewWidget';
if (!customElements.get('review-widget')) {
customElements.define('review-widget', ReviewWidget);
}
if (!window.customElements) {
console.warn('[review-widget] Custom Elements не підтримуються');
}
Публікація через CDN з SRI-хешем гарантує цілісність ресурсу. Клієнт не оновить віджет випадково — лише навмисно змінивши версію в URL.
Коли без iframe не обійтися
Для IE11 та браузерів старших за 2017 рік Custom Elements потребують поліфіл. Якщо аудиторія вашого сайту включає таких користувачів (частка >5%), ми підключаємо поліфіл або пропонуємо гібридну схему: для старих браузерів — iframe з postMessage, для сучасних — Custom Elements. Термін розробки збільшується на 1–2 тижні.Як відбувається розробка та інтеграція?
- Аналітика. Вивчаємо оточення клієнта: браузери, бібліотеки, вимоги до SEO. Заміряємо поточний LCP та CLS.
- Проектування. Визначаємо API атрибутів, подій, структуру даних. Проектуємо Shadow DOM.
- Реалізація. Пишемо Custom Element, стилі, API-клієнт. Налаштовуємо збірку (Rollup + Terser) та CDN.
- Тестування. Перевіряємо на реальних хост-сайтах: Chrome 54+, Firefox 63+, Safari 10.1+, Edge 79+. Заміряємо LCP (< 1.5 с), CLS (< 0.1), INP (< 200 мс).
- Деплой. Завантажуємо на CDN з SRI-хешем, надаємо клієнту скрипт та документацію.
Що входить у роботу
- Розробка кастомного HTML-елемента з ізоляцією через Shadow DOM.
- Документація з інтеграції (скрипт, атрибути, події).
- Тестування в цільових браузерах.
- Розміщення на CDN з SRI-хешем та версіонуванням.
- Підтримка протягом 1 місяця після запуску (виправлення багів, консультації).
Терміни орієнтовно
Для одного віджета середньої складності — від 2 до 4 тижнів. Складність зростає, якщо потрібен iframe-режим як fallback: додається до 2 тижнів на postMessage-комунікацію. Вартість розраховується індивідуально на основі вашого стеку та вимог. Замовте попередній аудит — його вартість 15 000 ₽ списується при замовленні розробки. Ми проаналізуємо оточення та запропонуємо оптимальне рішення.
Згідно з MDN Custom Elements, елементи повинні бути зареєстровані через customElements.define.
Ми займаємося веб-розробкою 5+ років, реалізували 30+ проектів з вбудовування віджетів. Зв'яжіться з нами для оцінки вашого проекту — ми проаналізуємо оточення та запропонуємо оптимальне рішення. Отримайте консультацію або замовте розробку віджета вже сьогодні.