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 storybook in lily-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