Definindo elementos com customElements.define
Registre uma classe de elemento personalizado no navegador.
Definindo elementos com customElements.define é uma aula grátis de HTML Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de HTML Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de HTML Academy inclui 4 aulas no total.
O que são elementos personalizados?
Os elementos personalizados permitem que você invente suas próprias tags HTML apoiadas por uma classe JavaScript. Depois de definidos, <my-card> se comporta como qualquer elemento nativo: pode ser escrito em HTML, consultado, estilizado, controlado por scripts e usado em estruturas sem alterações.
A exigência do hífen
Todo nome de elemento personalizado deve incluir pelo menos um hífen — user-avatar, app-button, my-card. O hífen distingue os elementos personalizados das tags HTML nativas atuais e futuras, e seu uso é exigido pela especificação.
Definindo uma classe
Um elemento personalizado é uma classe que estende HTMLElement (ou uma subclasse nativa). A classe pode declarar um construtor e retornos de chamada do ciclo de vida. As propriedades e os métodos públicos da classe tornam-se a interface de scripts do elemento.
class MyCard extends HTMLElement {
constructor() {
super();
this.textContent = "Hello from MyCard";
}
}Registrando com define
customElements.define("my-card", MyCard) registra a classe com o nome da tag. Após o registro, todo <my-card> existente e futuro no documento é convertido em uma instância da classe.
super() é obrigatório
O construtor deve chamar super() como sua primeira instrução antes de acessar this. Ignorar super() gera o erro "Failed to construct 'HTMLElement'". Trate isso como a regra padrão de construtores de classes JavaScript que de fato é.
Nenhuma leitura do DOM no construtor
O construtor não pode ler os atributos ou os filhos do elemento — eles talvez ainda não tenham sido analisados no momento da construção. Transfira a configuração que acessa o DOM para connectedCallback, que é executado somente depois que o elemento está no documento.
O registro é permanente
Um nome de elemento só pode ser registrado uma vez por página. Definir novamente o mesmo nome gera um NotSupportedError. Recarregue a página para testar alterações durante o desenvolvimento; em produção, registre cada componente uma vez na inicialização.
Camadas de compatibilidade
Os elementos personalizados estão disponíveis em todos os navegadores modernos. Para navegadores muito antigos (em sua maioria extintos), o polyfill webcomponents.js fornece uma alternativa. Projetos novos podem usar a implementação nativa e dispensar completamente essa camada de compatibilidade.
Detectando o status da definição
customElements.get("my-card") retorna a classe se ela estiver definida e undefined caso contrário. customElements.whenDefined("my-card") retorna uma promessa que é resolvida assim que o elemento é registrado — algo útil para códigos que precisam aguardar definições carregadas posteriormente.
customElements.whenDefined("my-card").then((Class) => {
console.log("MyCard is ready");
});Usando o elemento
Depois de definido, use o elemento exatamente como uma tag nativa: escreva-o em HTML (<my-card></my-card>), crie-o por meio de document.createElement("my-card") ou instancie-o por meio de new MyCard() e insira-o. Os três caminhos produzem a mesma instância atualizada.
Convenções de nomenclatura
Use como prefixo dos elementos personalizados o nome de um projeto ou empresa (cd-card, app-modal) para evitar conflitos com outras bibliotecas na mesma página. O ecossistema de componentes da Web não é empacotado — qualquer pessoa na sua página pode registrar qualquer nome, e o primeiro registro prevalece.
Verificação de conhecimentos
Por que todo nome de elemento personalizado deve conter um hífen?
Resumo
Os elementos personalizados são classes JavaScript que estendem HTMLElement, registradas por meio de customElements.define("name", Class), sendo obrigatório que o nome contenha um hífen. O construtor deve chamar super() primeiro e não deve ler o DOM; adie o trabalho com o DOM para connectedCallback. Os elementos definidos se comportam exatamente como tags nativas em todos os contextos.
Perguntas Frequentes
A aula “Definindo elementos com customElements.define” é grátis?
Sim — o texto completo de “Definindo elementos com customElements.define” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de HTML Academy, atualize para CoddyKit PRO. O curso de HTML Academy inclui 4 aulas no total.
O que vou aprender em “Definindo elementos com customElements.define”?
Registre uma classe de elemento personalizado no navegador. Você pratica HTML Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar HTML Academy?
Nenhuma experiência prévia é necessária. HTML Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Definindo elementos com customElements.define”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de HTML Academy?
Sim. Cada aula de HTML Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Definindo elementos com customElements.define
- connectedCallback e disconnectedCallback
- Atributos observados e attributeChangedCallback
- Estendendo elementos integrados