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
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.
01
- Rescue
- Hydration mismatches, broken reflection, shadow DOM style bleed and registry collisions all worked through to a clean paint.
02
- Design system build
- Lit component libraries scaffolded with proper theming, documentation, and consumer bindings for React, Vue and Angular.
03
- SSR and hydration
- @lit-labs/ssr set up on the server, components audited for client-only lifecycle hooks, hydration verified against the real pages.
04
- Lit 2 to 3 migrations
- Decorator mode switched, imports updated, and components audited for breaking changes with a passing test suite before cutover.
05
- 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.
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.