Shipping Lit web components?

Lit components refusing to reflect or hydrate? We sort it out.

Lit is Google's small library for writing web components that look like a modern framework. The sharp edges show up when a property is supposed to reflect to an attribute and quietly does not, when SSR hydration marks the tree as mismatched, or when shadow DOM slot styling behaves slightly differently in each browser. We work through the decorators, lifecycle and style scoping until the components behave the same in every consumer of them.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

lit-dev.log

still failing

What it is

Lit at a glance

Lit is Google's library for building web components: small, framework-agnostic custom elements that run natively in any modern browser. It is maintained by the same team that originally built Polymer and reshaped it around the native custom elements and shadow DOM standards. The current major release is Lit 3, with first-class TypeScript support, reactive properties, and lit-html for declarative templates.

Lit is used for design systems, cross-framework widgets, embeddable components, and apps that want a long-lived UI layer not tied to a specific framework's release cadence. It pairs with server-side rendering through @lit-labs/ssr, integrates cleanly into React, Vue, Angular and vanilla pages, and compiles to standard HTML that any modern browser understands.

Type
Web components library with reactive templates
First released
2019 as LitElement, Lit 2 in 2022, Lit 3 in 2023
License
BSD 3-Clause, free and permissive
Maintained by
Google and the Lit team
Typically used for
Design systems, cross-framework components, embeddable widgets, framework-agnostic UI

The honest version

Lit pros and cons

No technology is all upside. This is where Lit earns its place and where it tends to cause trouble.

Where Lit is strong

  • Standards-basedA Lit component is a real custom element. It runs in any modern browser without a runtime beyond Lit itself, and nothing ties it to a specific framework's lifecycle.
  • Small runtimeUnder 10kB gzipped for the core, which is unusual for anything that calls itself a component library and lets you ship a design system without weighing down the host app.
  • lit-html is cleaner than JSXTagged template literals with directives give you composition, reactivity and SSR output without a compile step, and the error messages reference the template rather than a transpiled artefact.
  • Works everywhereLit components drop into React, Vue, Angular, server-rendered pages and even plain HTML. Design systems built on Lit survive when the consumer picks a different framework.
  • Reactive properties are first classDecorators or static declarations give you typed, reactive properties with attribute reflection, which removes a lot of the boilerplate custom elements normally need.

Where Lit bites

  • Shadow DOM style scoping has edgesStyles that work in one shadow tree do not necessarily cascade into slotted children. ::part() and CSS variables help, but global theming across a design system takes real planning.
  • Property reflection is not automaticA property only reflects to its attribute if you declare reflect: true, and types other than string need converters. Many 'why is this attribute not updating' bugs trace to this.
  • SSR is possible but fiddly@lit-labs/ssr works, and hydration mismatches are still a regular occurrence when a component renders slightly differently server-side and client-side.
  • Legacy decorators painProjects on older TypeScript decorator settings can trip up on Lit 3's move to standard decorators. The migration is doable but not free.
  • Smaller ecosystem than ReactThere are many excellent Lit components but far fewer than React equivalents. For niche widgets you often end up building rather than installing.
  • Debugging shadow DOM is awkwardDevtools work, but inspecting styles across slots and shadow boundaries takes more clicks than a flat React tree, and new engineers often miss that.

Sound familiar?

Common Lit problems we fix

The Lit problems that bring people to us, and what you have once each one is fixed.

property 'open' has no corresponding attribute

A property never updates the matching attribute

The property was declared without reflect: true, or the type converter is missing. We update the property declaration and the attribute now stays in sync with the state.

Attributes reflect their properties

SSR hydration mismatch

Server-rendered output does not line up on hydration

A component rendered slightly differently on the server, often because of a browser-only API call in connectedCallback. We gate the client-only logic on hasUpdated and the hydration goes clean.

Hydration completes without warnings

shadow DOM: ::part() unsupported

Themeable parts fail in older browsers

The design system uses ::part() for consumer-side theming and a target browser does not support it. We add a CSS variable fallback so themes work everywhere even if the newer API is not available.

Theming works across browsers

CustomElementRegistry: already defined

A component is registered twice

Two bundles that each import the component land in the same page and the second customElements.define throws. We provide a guarded registration so a double import is a no-op rather than a crash.

Multiple bundles share one registry

FOUC before stylesheet adopted

Components flash unstyled on first render

The constructable stylesheet is adopted after the template renders, causing a brief unstyled frame. We move static styles into the static styles getter so the sheet is ready before first paint.

No more unstyled flash

legacy decorators metadata error

Upgrading to Lit 3 breaks decorator syntax

TypeScript project is on experimentalDecorators and Lit 3 wants standard decorators. We migrate the tsconfig and the component definitions together, with the imports updated to match.

Project builds on Lit 3

reflect: true with type Object

Objects serialise as [object Object]

Reflecting an object property to an attribute without a custom converter produces garbage. We switch to a JSON converter where reflection is actually needed, or stop reflecting the property entirely.

Attributes carry readable values

What we do

Lit help, from stuck components to shipped design systems

Engage us for a single misbehaving element, or let us run the whole Lit-based design system.

Rescue
Hydration mismatches, broken reflection, shadow DOM style bleed and registry collisions all worked through to a clean paint.
Design system build
Lit component libraries scaffolded with proper theming, documentation, and consumer bindings for React, Vue and Angular.
SSR and hydration
@lit-labs/ssr set up on the server, components audited for client-only lifecycle hooks, hydration verified against the real pages.
Lit 2 to 3 migrations
Decorator mode switched, imports updated, and components audited for breaking changes with a passing test suite before cutover.
Managed Tech
Version pinning across consuming apps, release notes reviewed per Lit update, and a US engineer on call when a browser release changes shadow DOM behavior.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Lit alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Lit questions

Something else? Call+1 737 727 7327

Why does my Lit property not update the matching attribute?

By default a property does not reflect to its attribute. You have to declare reflect: true on the property, and for anything other than a string or boolean you also need a converter. Teams often read the first page of the docs and assume reflection is automatic, which is where 'my attribute never updates' tickets come from. We fix the declarations and the attribute stays in sync.

Can Lit components be server-rendered?

Yes, through @lit-labs/ssr. The gotcha is hydration mismatches: anything that runs in connectedCallback and uses a browser-only API will produce different output on server and client. We gate client-only logic behind hasUpdated or firstUpdated, and audit each component for timing issues before deploying SSR to production.

Why do my Lit components flash unstyled on first paint?

Styles declared outside the static styles getter are adopted after the first render, which causes a brief flash. Move the stylesheet into the static styles field so it is adopted before the component mounts, and preload the component bundle in the host page so the custom element is upgraded before it is painted.

How do consumers theme a Lit design system?

CSS variables and ::part() are the two tools. CSS variables are supported everywhere and should carry colors, spacings and typography. ::part() exposes specific elements inside the shadow DOM for direct styling by the consumer, but it is a newer API and an older browser needs a variable-based fallback. We design the theming contract once so consumers do not have to fight the shadow boundary.

How much does Lit help cost?

Quotes are free. Describe the component library, the consuming apps and what is going wrong, and a US engineer will come back with a scoped price before any code moves.

Free estimate

Lit giving you trouble?

Share the component source and the failure mode, and a US engineer will reply with a plan and a price.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.