Web Components tutorial
Native custom elements with no framework runtime. Each renders a real <button> or <input> in the light DOM,
so forms, CSS and querySelector work as on hand-written HTML.
What you'll build
A small contact form with labelled fields and a submit button, wired with a few lines of script, first bare, then styled, in about 10 minutes.
Before you start
You need Node.js and a bundler or any setup that resolves bare module
imports. The catalog covers 626 of the 661 components; the table
sub-elements and a few list-item families are left out, because an
autonomous custom element cannot stand in for a <tr> or an <li>.
Step 1 — Install and register
npm install @lilydesignsystem/web-components-headless <script type="module">
import "@lilydesignsystem/web-components-headless";
</script> Importing the package defines every element, each named lily- plus the component's slug: <lily-button>, <lily-text-input>, <lily-range-fieldset>.
Step 2 — Your first component
<lily-button type="submit">Send</lily-button> The element renders a real <button class="button"> inside itself, so Enter, Space and the button role are native. Attributes
you add pass through to that inner element.
Step 3 — Compose a small form
<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> prevents the page navigation and lets the submit event bubble, so your script decides what happens.
The inputs are genuine form controls, so FormData reads them.
Check your work: press Tab through the form,
then submit it: the console shows name and email. Leave a field empty and the browser's own required check stops the submit.
Step 4 — Style it
The class hooks sit on the inner elements, so the 63 themes and your own CSS target them as on plain HTML:
<link rel="stylesheet" href="/themes/light.css" />
<style>
.button { padding: 0.75rem 1.5rem; }
lily-field { display: block; margin-block-end: 1rem; }
</style> There is no shadow DOM to pierce: nothing is hidden from your stylesheet or from assistive technology.
Step 5 — See it all working
- Every element has a story:
pnpm run storybookinlily-design-system-web-components-headless. - The helpers ship as custom elements too:
<lily-theme-picker>, the data grid, the calendar and the others (@lilydesignsystem/web-components-*).
Next steps
- Training — eight modules, each with an exercise and a self-check.
- Accessible forms — errors, an error summary and focus.
- Theming — runtime theme switching.
- Component catalog — the full reference.