Tutorial de Web Components
Elementos personalizados nativos, sem runtime de framework. Cada um gera um
<button> ou um <input> real no DOM leve, por isso formulários, CSS e querySelector funcionam como em HTML escrito à mão.
O que você vai construir
Um pequeno formulário de contacto com campos rotulados e um botão de envio, ligado com algumas linhas de script, primeiro simples e depois estilizado, em cerca de 10 minutos.
Antes de começar
Precisa de Node.js e de um bundler ou de qualquer configuração que resolva importações de módulos sem caminho. O catálogo cobre 626 dos 661 componentes; os subelementos de tabela e algumas famílias de itens de lista ficam de fora, porque um elemento personalizado autónomo não pode substituir um <tr>
ou um <li>.
Passo 1 — Instalar e registar
npm install @lilydesignsystem/web-components-headless
<script type="module">
import "@lilydesignsystem/web-components-headless";
</script>
Importar o pacote define cada elemento, com o nome
lily- mais o identificador do componente:
<lily-button>, <lily-text-input>,
<lily-range-fieldset>.
Passo 2 — O seu primeiro componente
<lily-button type="submit">Send</lily-button>
O elemento gera um <button class="button">
real dentro de si, por isso Enter, Espaço e o papel de botão são nativos. Os atributos que acrescentar passam para esse elemento interno.
Passo 3 — Compor um pequeno formulário
<lily-form label="Contact us">
<lily-field label="Full name" required>
<lily-text-input label="Full name" name="name" autocomplete="name" required></lily-text-input>
</lily-field>
<lily-field label="Email" required>
<lily-email-input label="Email" name="email" required></lily-email-input>
</lily-field>
<lily-button type="submit">Send</lily-button>
</lily-form>
<script type="module">
const form = document.querySelector("lily-form form");
form.addEventListener("submit", () => {
const data = new FormData(form);
console.log(Object.fromEntries(data));
});
</script>
<lily-form> impede a navegação da página e deixa o evento
submit propagar-se, por isso o seu script decide o que acontece. Os campos são controlos de formulário genuínos, por isso FormData lê-os.
Verifique o seu trabalho: prima Tab para percorrer o formulário e depois envie-o: a consola mostra name e
email. Deixe um campo vazio e a verificação
required do próprio navegador impede o envio.
Passo 4 — Estilizar
As classes estão nos elementos internos, por isso os 63 temas e o seu próprio CSS visam-nos como em HTML simples:
<link rel="stylesheet" href="/themes/light.css" />
<style>
.button { padding: 0.75rem 1.5rem; }
lily-field { display: block; margin-block-end: 1rem; }
</style>
Não há shadow DOM a atravessar: nada fica escondido da sua folha de estilos nem das tecnologias de apoio.
Passo 5 — Ver tudo a funcionar
- Cada elemento tem uma story:
pnpm run storybookemlily-design-system-web-components-headless. -
Os ajudantes também existem como elementos personalizados:
<lily-theme-picker>, a grelha de dados, o calendário e os restantes (@lilydesignsystem/web-components-*).
Próximos passos
- Formação — oito módulos, cada um com um exercício e uma autoavaliação.
- Formulários acessíveis — erros, um resumo de erros e o foco.
- Temas — mudar de tema em tempo de execução.
- Catálogo de componentes — a referência completa.