Web e Desenvolvimento

Web Components: Construa Componentes de UI Reutilizáveis com JavaScript Vanilla

Web Components: Build Reusable UI Components with Vanilla JavaScript

Aprenda Web Components passo a passo construindo um cartão de UI reutilizável com Custom Elements, Shadow DOM, HTML Templates, slots e módulos JavaScript. Nenhum framework ou ferramentas de build são necessários.

Web Components: Crie Componentes de UI Reutilizáveis com JavaScript Puro

Imagine criar um cartão para o seu site e depois usá-lo em um tema WordPress, uma extensão Joomla ou um aplicativo autônomo, sem reescrevê-lo para cada ambiente.

Essa é a promessa dos Web Components: ferramentas nativas do navegador para construir elementos HTML reutilizáveis. Nenhum React, Vue, pacote npm ou bundler é necessário para o exemplo que vamos construir.

Ao final deste tutorial, você terá um componente <ui-card> funcional com conteúdo personalizável, estilos isolados, uma variante em destaque, um botão de descartar e um evento público. Vamos construí-lo em pequenos passos para que você possa ver o que cada tecnologia contribui.

O que você vai construir

Nosso componente final vai suportar este HTML:

<ui-card variant="featured">
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

Prévia visual — cartões padrão e em destaque

Prévia visual de cartões padrão e em destaque de Web Component

Esta prévia é o alvo do design, não uma captura de tela de uma biblioteca não relacionada. Vamos reproduzi-la usando o código abaixo.

1. Entenda os quatro blocos de construção

Os Custom Elements nos permitem registrar uma nova tag HTML e seu comportamento em JavaScript. O Shadow DOM dá ao elemento seu próprio DOM interno e estilos com escopo. Os templates HTML e slots nos permitem reutilizar a estrutura enquanto inserimos conteúdo diferente em cada instância. Os ES Modules nos permitem carregar o componente a partir de um arquivo JavaScript normal.

São recursos separados. Um Custom Element não precisa usar o Shadow DOM, e você não precisa de um framework para usar nenhum deles.

2. Crie os arquivos do projeto

Crie esta estrutura no seu editor:

web-components-demo/
├── index.html
├── components/
│   └── ui-card.js
└── css/
    └── main.css

Coloque isto em index.html:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Web Components Demo</title>
  <link rel="stylesheet" href="./css/main.css">
  <script type="module" src="./components/ui-card.js"></script>
</head>
<body>
  <main class="container">
    <h1>Reusable UI Components</h1>
    <p>Let's build a reusable card without a framework.</p>
    <ui-card></ui-card>
  </main>
</body>
</html>

Adicione os estilos de nível de página a css/main.css:

body {
  margin: 0;
  background: #f4f6f9;
  color: #1f2937;
  font-family: system-ui, sans-serif;
}
.container {
  max-width: 900px;
  margin: 60px auto;
  padding: 0 20px;
}
ui-card {
  display: block;
  margin-top: 24px;
}

Execute um servidor HTTP local a partir do diretório do projeto, por exemplo:

python -m http.server 8000

Visite http://localhost:8000. O título aparece, mas o cartão ainda não tem conteúdo visível. Use um servidor HTTP em vez de abrir o index.html com o file://: as regras de carregamento de módulos do navegador podem bloquear importações de arquivos locais.

3. Registre seu primeiro Custom Element

Crie o components/ui-card.js:

class UiCard extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from a Web Component!';
  }
}

customElements.define('ui-card', UiCard);

Atualize a página. Você deve ver agora:

Resultado esperado — Passo 3

Saída do primeiro custom element

O HTMLElement fornece o comportamento normal do DOM. O connectedCallback() é executado quando o elemento se conecta ao documento. O customElements.define() associa a classe à tag HTML.

O hífen em ui-card é obrigatório para nomes de Custom Elements autônomos. O callback pode ser executado novamente se o elemento for desanexado e reinserido, o que importa quando adicionamos lógica de inicialização.

4. Dê ao cartão seu próprio design com o Shadow DOM

Substitua o ui-card.js por:

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });

    shadow.innerHTML = `
      <style>
        article {
          padding: 24px;
          background: white;
          border: 1px solid #dce3ec;
          border-radius: 12px;
        }
        h2 {
          margin: 0 0 12px;
          color: #2563eb;
        }
      </style>
      <article>
        <h2>My reusable card</h2>
        <p>This content lives inside Shadow DOM.</p>
      </article>
    `;
  }
}

customElements.define('ui-card', UiCard);

Resultado esperado — Passo 4

Cartão estilizado dentro do Shadow DOM

Abra o DevTools, inspecione o <ui-card> e expanda o #shadow-root (open). Você verá o article interno e a folha de estilos.

Diferente dos seletores comuns de documento, o CSS global como o article { border: none } normalmente não alcança esta árvore shadow. Propriedades herdadas e custom properties do CSS ainda podem atravessar o limite. O Shadow DOM encapsula a apresentação; ele não é um sandbox de segurança.

A proteção do if (this.shadowRoot) evita anexar uma segunda shadow root se o elemento se reconectar.

5. Separe o layout com um template HTML

Embutir tudo dentro do connectedCallback() se torna complicado à medida que um componente cresce. Vamos definir a marcação uma vez e cloná-la para cada cartão.

Substitua o arquivo por:

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 {
      margin: 0 0 12px;
      color: #2563eb;
    }
  </style>
  <article>
    <h2>My reusable card</h2>
    <p>Created from an HTML template.</p>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('ui-card', UiCard);

O template.content é um fragmento de documento. O cloneNode(true) copia toda a estrutura para a shadow tree de cada cartão. O template em si não é renderizado até que o clonemos e o inseramos.

Esta versão parece quase idêntica. A melhoria é arquitetural: um template pode servir a muitas instâncias.

6. Insira conteúdo diferente usando slots

Um cartão reutilizável não é útil se toda instância tiver o mesmo título. Substitua apenas a declaração do template no topo do ui-card.js pelo seguinte; mantenha a classe e o código de registro do Passo 5.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 { margin: 0 0 12px; color: #2563eb; }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
  </style>
  <article>
    <h2><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

Agora substitua o <ui-card></ui-card> no index.html:

<ui-card>
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

Resultado esperado — Passo 6

Cartão com slots nomeados e link de ação

O slot nomeado recebe o elemento marcado como slot="title". O slot sem nome recebe o parágrafo. O slot de ação recebe o link. O texto de fallback de um slot aparece se nada for atribuído a ele.

O layout vive no componente; as palavras e os links reais permanecem no HTML da página. Isso é especialmente útil para conteúdo de CMS. Substitua o /tutorial por um destino real no seu projeto.

7. Crie uma variante em destaque com CSS

Dentro do bloco <style> do template, adicione:

:host {
  display: block;
}
:host([variant="featured"]) article {
  background: #eff6ff;
  border-color: #93c5fd;
}

Depois substitua o único cartão no index.html por dois cartões:

<ui-card>
  <span slot="title">Standard card</span>
  <p>This card uses the default appearance.</p>
</ui-card>

<ui-card variant="featured">
  <span slot="title">Featured card</span>
  <p>This card has a highlighted appearance.</p>
</ui-card>

Resultado esperado — Passo 7

Variantes de cartão padrão e em destaque

Este é um recurso particularmente útil do :host(): ele estiliza o componente com base nos atributos do custom element. Se o JavaScript alterar o variant depois, o CSS se atualiza automaticamente. Nenhum attributeChangedCallback() é necessário para uma mudança puramente conduzida por CSS.

8. Adicione um botão de descartar e um evento público

Vamos tornar o cartão interativo. Dentro do <article> do template, adicione este botão antes do título:

<button class="dismiss" type="button" aria-label="Dismiss card">
  ×
</button>

Adicione estas regras ao CSS do template:

article { position: relative; }
.dismiss {
  position: absolute;
  top: 12px;
  right: 12px;
  width: 32px;
  height: 32px;
  border: 0;
  border-radius: 6px;
  background: transparent;
  color: #475569;
  font-size: 24px;
  cursor: pointer;
}
.dismiss:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

Substitua o connectedCallback() na classe por:

connectedCallback() {
  if (this.shadowRoot) return;

  const shadow = this.attachShadow({ mode: 'open' });
  shadow.appendChild(template.content.cloneNode(true));

  shadow.querySelector('.dismiss').addEventListener('click', () => {
    this.dispatchEvent(new CustomEvent('card-dismissed', {
      bubbles: true,
      composed: true
    }));
    this.remove();
  });
}

No index.html, adicione este script antes do </body>:

<script type="module">
  document.addEventListener('card-dismissed', () => {
    console.log('A card was dismissed.');
  });
</script>

Abra o console do navegador e clique em ×. O cartão desaparece e o console exibe a mensagem.

O evento fornece um ponto de integração público: o aplicativo ao redor não precisa saber nada sobre o botão interno do cartão. O bubbles faz o evento borbulhar; o composed permite atravessar um limite shadow quando aplicável. Aqui o evento se origina no próprio elemento host.

9. Versão final completa: copie e use

Você já pode substituir todo o conteúdo do components/ui-card.js por esta versão consolidada. Ela adiciona personalização por CSS e partes exportadas, mantendo o comportamento construído nos passos anteriores.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    :host {
      display: block;
      color: #1f2937;
      font-family: system-ui, sans-serif;
    }
    article {
      position: relative;
      box-sizing: border-box;
      padding: 24px;
      background: var(--card-background, #fff);
      border: 1px solid var(--card-border, #dce3ec);
      border-radius: 12px;
    }
    :host([variant="featured"]) article {
      background: var(--card-featured-background, #eff6ff);
      border-color: var(--card-featured-border, #93c5fd);
    }
    h2 {
      margin: 0 36px 12px 0;
      color: var(--card-title-color, #2563eb);
      font-size: 1.25rem;
    }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
    .dismiss {
      position: absolute;
      top: 12px;
      right: 12px;
      width: 32px;
      height: 32px;
      border: 0;
      border-radius: 6px;
      background: transparent;
      color: #475569;
      font-size: 24px;
      cursor: pointer;
    }
    .dismiss:hover { background: rgba(0, 0, 0, 0.06); }
    .dismiss:focus-visible {
      outline: 2px solid #2563eb;
      outline-offset: 2px;
    }
  </style>
  <article part="container">
    <button class="dismiss" type="button"
            aria-label="Dismiss card">×</button>
    <h2 part="title"><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));

    shadow.querySelector('.dismiss').addEventListener('click', () => {
      this.dispatchEvent(new CustomEvent('card-dismissed', {
        bubbles: true,
        composed: true,
        detail: {
          variant: this.getAttribute('variant') || 'default'
        }
      }));
      this.remove();
    });
  }
}

if (!customElements.get('ui-card')) {
  customElements.define('ui-card', UiCard);
}

Diferente de uma demonstração rápida, esta versão não tenta anexar a shadow root duas vezes, não insere conteúdo não confiável com o innerHTML e não depende de um framework. A string do template é controlada pelo desenvolvedor; nunca interpole entrada não confiável do usuário nela.

10. Estilize a partir do site que o hospeda

O Shadow DOM não tem a intenção de tornar a personalização impossível. Ele incentiva você a definir uma interface de estilização intencional.

No css/main.css, adicione:

ui-card {
  --card-border: #cbd5e1;
  --card-title-color: #0f766e;
}
ui-card::part(container) {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}

As custom properties são herdadas pela shadow tree e controlam os valores que expusemos. O atributo part="container" permite que o CSS externo tenha como alvo um elemento interno selecionado com o ::part(container).

Se você precisar de um fundo de destaque diferente, use o --card-featured-background. Isso é preferível a forçar os consumidores a dependerem da estrutura exata do DOM interno.

11. Reutilize o cartão em WordPress, Joomla ou HTML simples

Copie o ui-card.js para o site de destino e carregue-o como um módulo JavaScript:

<script type="module" src="/assets/js/ui-card.js"></script>

Depois use o <ui-card> na marcação da página. No WordPress, registre os assets por meio das APIs de carregamento de script suportadas pelo tema ou plugin, usando o suporte a módulos adequado à sua versão do WordPress. No Joomla, use o Web Asset Manager para registrar e carregar o módulo. Não espalhe tags de script fixas por modelos de produção.

Para um cartão gerado por CMS, renderize o título, o parágrafo e o link como HTML com slot. Escape o conteúdo e os atributos de acordo com as regras de saída do CMS.

Benefício prático: um módulo Joomla e um bloco WordPress podem ambos emitir a mesma tag customizada enquanto compartilham uma única implementação de componente. Cada CMS permanece responsável por buscar e escapar seu próprio conteúdo.

12. Acessibilidade, SEO e melhoria progressiva

Use controles HTML nativos dentro dos componentes sempre que possível. Nossa ação de descartar usa um button real, que fornece semântica de ativação por teclado, e um aria-label porque o × sozinho não é descritivo.

Se um usuário descartar um cartão com o foco do teclado, considere para onde o foco deve ir em seguida em uma interface mais complexa. Diálogos, menus e caixas de combinação precisam de muito mais comportamento de acessibilidade do que este exemplo.

Mantenha o conteúdo importante em marcação significativa do light-DOM onde for prático. Se o JavaScript falhar, o navegador não vai atualizar o <ui-card>; o título e o parágrafo com slot permanecem no documento, embora a casca estilizada do componente e o botão de descartar não existam.

Para os mecanismos de busca, não presuma que o conteúdo apenas de JavaScript é indexado de forma idêntica em todos os rastreadores. O conteúdo crítico deve estar disponível no HTML inicial ou por meio de uma estratégia de renderização apropriada.

O Shadow DOM também tem limitações: seletores de CSS comuns de documento não estilizam nós internos, e alguns relacionamentos de ID do ARIA não podem atravessar limites shadow. Projete as APIs dos componentes com essas restrições em mente.

13. Os Web Components são sempre mais rápidos?

Não necessariamente. Os Web Components evitam exigir um runtime de framework específico, mas o desempenho depende da quantidade de JavaScript, da complexidade do DOM, da frequência de renderização e da arquitetura da aplicação.

Um cartão pequeno é um bom candidato. Centenas de elementos complexos com reconstrução desnecessária do DOM ainda podem ser lentos. Reutilize templates, evite renderização completa repetida e meça o desempenho real.

Para uma aplicação grande já construída em torno do gerenciamento de estado e do roteamento de um framework, usar os próprios componentes desse framework pode ser mais simples. Os Web Components brilham quando um elemento de UI estável precisa atravessar limites de frameworks ou CMS.

14. Solução de problemas

Sintoma Causa provável O que verificar
O cartão está vazio O módulo não carregou Console do DevTools, URL, tipo MIME do servidor
O customElements.define dispara erro Nome inválido ou duplicado Requisito do hífen e proteção de registro
O CSS não se aplica dentro do cartão Limite do Shadow DOM Use custom properties, :host ou ::part
O conteúdo aparece no lugar errado Incompatibilidade do nome do slot Compare o slot="title" com o <slot name="title">
Clicar em descartar não faz nada Botão do template ausente Inspecione a shadow tree e o console
O componente falha ao ser movido A inicialização é executada duas vezes Proteja a criação da shadow root
O link leva a um 404 A URL de exemplo não foi substituída Use um destino existente

Lembre-se de que o connectedCallback() pode ser executado mais de uma vez. A proteção no nosso exemplo final mantém a inicialização única; componentes mais sofisticados podem precisar anexar e remover observadores externos ou event listeners globais durante seu ciclo de vida de conexão.

15. Quando você deve usar Web Components?

Escolha-os quando um componente precisar de uma interface HTML reutilizável e documentada em vários sites, frameworks ou ambientes de CMS. Cartões, notificações, widgets de produto e pequenas ferramentas interativas são bons candidatos.

Ignore a abstração quando algumas linhas de HTML e CSS comuns já resolvem o problema. E não recrie controles nativos sem um motivo forte.

Um teste útil: outra aplicação se beneficiaria de usar este elemento sem saber como ele foi implementado? Se sim, um Web Component vale a pena considerar.

Conclusão

Você construiu um componente reutilizável real, não apenas leu sobre uma API do navegador. Ele tem uma tag customizada, estilização com escopo, conteúdo configurável, uma variante em destaque e um evento que outro código pode escutar.

Comece com um componente que aparece repetidamente nos seus projetos. Dê a ele uma pequena API pública, teste-o em mais de um layout e mantenha suas dependências mínimas.

O valor a longo prazo dos Web Components não é que eles substituam todos os frameworks. É que eles permitem que elementos de interface úteis sobrevivam ao framework ou CMS que os hospedou pela primeira vez.

Referências oficiais