Skip to content

Lit

Lit elements, rendered on the server into a declarative shadow root with @lit-labs/ssr and adopted in place in the browser with @lit-labs/ssr-client. The droplet below is a Lit element served by the demo server: its load sets the start, Lit renders it to HTML with its styles in the shadow root, and the button works once the bundle hydrates it.

Live: rendered by the demo server, hydrated in this page.
src/droplets/counter-lit/+droplet.lit.ts
import { css, html } from "lit";
import { DropletElement } from "@dropletsjs/renderer-lit/element";
import type { DropletProps } from "./$types";
export const ssr = true;
export const hydrate = true;
export default class Counter extends DropletElement<DropletProps> {
static override properties = { added: { state: true }, hydrated: { state: true } };
// The shadow root keeps the page's stylesheets out, src/app.css included;
// custom properties inherit into it, so the card uses its --demo-* colors.
static override styles = css`
section {
max-width: 36rem;
padding: 1rem 1.25rem;
border: 1px solid var(--demo-line);
border-radius: var(--demo-radius);
background: var(--demo-surface);
}
p {
margin: 0;
}
p + p {
margin-top: 0.75rem;
}
.row {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 0.75rem;
}
.tag {
padding: 0.125rem 0.5rem;
border: 1px solid var(--demo-line);
border-radius: 999px;
background: var(--demo-sunken);
color: var(--demo-muted);
font: 500 0.75rem/1.4 var(--demo-mono);
}
output {
font-size: 1.25rem;
font-weight: 600;
}
button {
min-height: 2.25rem;
padding: 0.375rem 0.875rem;
border: 0;
border-radius: var(--djs-radius-sm, 4px);
background: var(--demo-accent);
color: var(--demo-on-accent);
font: inherit;
font-size: 0.875rem;
font-weight: 600;
cursor: pointer;
}
button:focus-visible {
outline: 2px solid var(--djs-focus, var(--demo-accent));
outline-offset: 2px;
}
.muted {
color: var(--demo-muted);
font-size: 0.875rem;
}
`;
declare added: number;
declare hydrated: boolean;
constructor() {
super();
// Set here, not as class fields: a field would hide the property Lit defines.
this.added = 0;
this.hydrated = false;
}
// Runs in the browser only, once the server's shadow root is adopted. The
// change waits for that update to finish: Lit warns of one made during it.
override firstUpdated() {
void this.updateComplete.then(() => (this.hydrated = true));
}
override render() {
// What the server load returned. Always the value: the renderer waits for it.
const { framework, start } = this.data;
return html`
<section data-hydrated=${String(this.hydrated)}>
<p class="row"><span class="tag">counter · ${framework}</span></p>
<p class="row">
<output aria-live="polite">${start + this.added}</output>
<button type="button" @click=${() => (this.added += 1)}>Add one</button>
</p>
<p class="muted">
${this.hydrated ? `Hydrated: ${framework} runs the button in this tab.` : `Server HTML: the button works once ${framework} hydrates.`}
</p>
</section>
`;
}
}
Terminal window
npx djs add counter --framework lit

It installs what the project lacks and adds lit() to renderers invite.config.ts, asking first, then writes src/droplets/counter/+droplet.lit.ts.

Every step it takes is in Add a renderer. What it installs for Lit:

PackageInstalled as
@dropletsjs/renderer-lita dev dependency, at exactly the version of @dropletsjs/droplets you have
lit@^3.3.0a dependency

By hand:

Terminal window
npm install lit
npm install -D @dropletsjs/renderer-lit

then import { lit } from "@dropletsjs/renderer-lit" and lit() in renderers.

File What it is
+droplet.lit.ts, +droplet.lit.js The component: the file default-exports a LitElement class. Its flags are named exports.
+error.lit.ts, +error.lit.js The error page, optional, a LitElement class too.
+droplet.ts, +droplet.server.ts The loads, as for every framework: Writing droplets.

.lit.ts is Lit’s alone: any +droplet.lit.ts is a Lit droplet, and a plain +droplet.ts next to it stays the universal load. The packages lit, lit-html, lit-element, @lit/reactive-element, @lit-labs/ssr-client and @dropletsjs/renderer-lit are Lit’s own: a droplet of another framework that reaches them, through any chain of imports, fails the build.

src/droplets/hello/+droplet.lit.ts
import { css, html } from "lit";
import { DropletElement } from "@dropletsjs/renderer-lit/element";
import type { DropletProps } from "./$types";
export const hydrate = true;
export default class Hello extends DropletElement<DropletProps> {
// Added to the ones DropletElement declares: Lit merges them.
static override properties = { clicks: { state: true } };
static override styles = css`h1 { font-family: system-ui, sans-serif; }`;
declare clicks: number;
constructor() {
super();
this.clicks = 0;
}
override render() {
return html`
<h1>${this.data.greeting}</h1>
<button @click=${() => (this.clicks += 1)}>${this.clicks}</button>
<slot></slot>
`;
}
}
src/droplets/hello/+error.lit.ts
import { css, html } from "lit";
import { DropletErrorElement } from "@dropletsjs/renderer-lit/element";
import type { DropletErrorProps } from "./$types";
export default class HelloError extends DropletErrorElement<DropletErrorProps> {
static override styles = css`.oops { color: crimson; }`;
override render() {
return html`<p class="oops">${this.error.message}</p><slot></slot>`;
}
}
Server rendering yes, with @lit-labs/ssr: ssr = true, the default; ssr = false renders it in the browser only
hydrate true (the default), "visible", "interactive", false
Prerendering yes: prerender = true with entries
Forms enhance() of @dropletsjs/renderer-lit/form, a Lit directive
Runtimes Node, Bun, Deno and Cloudflare Workers render alike

Importing another framework, even through a neutral file, stops vite build, and the vite dev server reports it too:

droplets: a lit droplet imports vue code: src/droplets/counter/+droplet.lit.ts -> vue/dist/vue.runtime.esm-bundler.js. A droplet uses its own framework's modules and neutral code only.

Flags are read from +droplet.lit.ts alone. A flag that is not a literal (export const hydrate = isMobile) is ignored, with a warning under vite dev and vite build; a flag exported from +droplet.ts or +droplet.server.ts is ignored.

One mistake is caught when the droplet renders, not at build: a default export that is no LitElement class answers 500, with counter: the droplet component must default-export a LitElement class (…); the renderer defines it in the server’s log.

  • The element and its name. The renderer defines the class itself, as <element>-<droplet id> (<element>-<droplet id>--error for the error page), <element> being the droplets server’s element name. The demo’s is <djs-demo-counter-lit>, inside <djs-demo>. Don’t call customElements.define (or use @customElement) in a droplet file; lit({ prefix }) changes the prefix: a lowercase letter, then lowercase letters, digits and hyphens.

  • Properties. The element gets data and form (or error) as properties, never attributes, and actionUrl(name?), the URL of a form action, the same string on the server and in the browser. DropletElement and DropletErrorElement of @dropletsjs/renderer-lit/element declare them; a plain LitElement declares them itself with attribute: false. Declare fields, never initialize them as class fields (data = …): a class field hides the property Lit defines. Give state its initial value in the constructor, as the demo does.

  • Data is always a value. Lit has no suspense: when a droplet mounts in the browser, the renderer waits for data before it renders, and a rejection renders the error page instead.

  • Declarative shadow DOM. @lit-labs/ssr prints the element with a declarative shadow root (<template shadowrootmode="open">), its static styles inside, and the defer-hydration attribute. In the browser, the renderer’s client setup loads lit-element-hydrate-support once per page, before any droplet defines its class; hydrate then adopts the server’s nodes in place, without rendering them again. firstUpdated runs then, which is where the demo sets hydrated.

  • Markup inserted with innerHTML. The HTML parser attaches a declarative shadow root only while it parses a page: a fragment a host inserts with innerHTML, like the ones the droplet element fetches itself after a form action or an edit in dev, keeps it as an inert <template>. hydrate attaches those first, innermost first, so such a fragment hydrates like one in the page. Until its script runs, it shows nothing of its shadow content.

  • Styles live in the shadow root. Write them as static styles. The droplet’s style.css, a CSS file a component imports, the shared css.path stylesheet (Tailwind included) and the host’s styles reach the light DOM only: the element itself and the host’s children. They never reach inside the shadow root, so the droplet’s scoped prefix has nothing to scope there. Inherited properties (font, color) and CSS custom properties flow in: theme a Lit droplet with custom properties set in src/app.css or by the host. The demo’s counter draws its card with the --demo-* properties apps/demo’s src/app.css sets on <djs-demo>.

  • Children: the host’s children are the element’s light-DOM child; a <slot> in the template shows them.

  • One registry per page. customElements holds one class per name, forever. Two droplets servers on one page keep apart by their element names, which are distinct already. An edited module under vite dev defines its new class under <tag>--v2, --v3, …; when the markup’s tag is held by another class, the droplet mounts afresh, with a warning in the console, rather than adopting nodes it did not render.

  • Forms in the shadow root post natively, to this.actionUrl("name"). To post them by fetch and update in place, enhance() is enhanceDropletForm as a Lit directive, released when the form leaves the page:

    import { enhance } from "@dropletsjs/renderer-lit/form";
    import type { DropletActions } from "./$types";
    html`<form method="post" action=${this.actionUrl()} ${enhance<DropletActions>()}>…</form>`;
  • hydrate = "interactive" works through the shadow root: the events that start it (pointerdown, focusin, keydown, click) are composed, so they reach the droplet element from inside, and a click replayed after hydration reaches the element that was clicked, not the shadow host.

  • Cloudflare Workers. Lit’s default builds expect a DOM and fail on Workers as they load. The renderer bundles Lit into the server build and swaps in Lit’s own server build (lit-html/node/…, @lit/reactive-element/node/…), which runs on Lit’s DOM shim with no Node API. apps/demo, which serves the droplet on this page, builds for Workers too, and its tests render this counter under wrangler dev.

  • Hot updates: Lit has no HMR of its own. Under vite dev with dev.strategy: "hmr" (the default), an edit to a component remounts the droplet in place, under a new tag, without a page reload, and its state starts over. An edit to the load brings new data to the live element. See Hot updates.

The renderer runs rendererConformance() like every other, with css: false: a component’s styles live in its shadow root, so the client build extracts none. The kit renders the server side in a worker thread, where Lit’s DOM shim finds no happy-dom and defines its elements apart from the browser bundles’; its DOM checks look into shadow roots and through slots, and its HTML checks ignore Lit’s <!--lit-part--> comments. The renderer’s own vitest suite covers the server side further, a Workers build included, and Playwright checks in real Chromium what only a browser shows: the parser attaching declarative shadow roots, styles inside the shadow root, and the replayed click inside it.

examples/frameworks/lit has one droplet per mode (client, ssr-hydrate with an error page, ssr-nohydrate) and a fourth, guestbook, with a form action posted from inside a shadow root, natively and through enhance(). From a clone of the repository:

Terminal window
pnpm install && pnpm build
pnpm --filter @dropletsjs/example-lit dev # http://localhost:5173: the devtools page

pnpm --filter @dropletsjs/example-lit build then start serves it on http://localhost:8000; /droplets/ssr-hydrate?who=Ana is the fragment a host pastes into its page.