Common Lit Mistakes

Why a Consolidated Mistakes Reference Helps

Individual lessons cover mistakes specific to their own topic (properties, events, styling, and so on). Having them all gathered in one place is useful specifically for debugging sessions: when a component behaves unexpectedly, scanning this consolidated list is often faster than guessing which earlier lesson's pitfall you've hit.

// If a component "isn't updating," check these first, in order:
// 1. Did you mutate an object/array in place instead of replacing it?
// 2. Is the field actually declared with @property()/@state()?
// 3. Are you reading this.shadowRoot synchronously before awaiting updateComplete?

This three-item checklist alone resolves a large share of 'my Lit component won't update' debugging sessions.

Mistake Categories Covered

1. Reactive properties and change detection
2. Lifecycle and cleanup
3. Templates and directives
4. Styling and Shadow DOM
5. Events and composition
6. TypeScript and tooling

• Each category below links conceptually back to its full dedicated lesson earlier in the course.
• Use this page as a fast lookup during debugging, not as your first introduction to any of these topics.
• Several mistakes recur across categories in slightly different forms (e.g. reference equality issues in both properties and repeat() keys).
• New mistakes will surface as you build more complex components — treat this as a living, not exhaustive, list.

Common Mistakes by Category

The highest-frequency mistakes across the entire course, organized by topic.

A Practical Debugging Workflow

When a Lit component misbehaves, working through a consistent short sequence of checks resolves most issues faster than ad hoc guessing.

• Check the browser console for warnings or errors first — Lit surfaces many misuse cases there directly.
• Confirm the field in question is actually declared reactive (@property()/@state() or in static properties).
• For object/array properties, confirm you're replacing the reference, not mutating in place.
• For DOM-reading code, confirm you're awaiting updateComplete before inspecting the result.
• For styling issues, confirm whether the problem is Shadow DOM encapsulation working as intended, not a bug.

Mistakes That Only Surface as a Codebase Grows

Some issues — inconsistent property naming conventions, duplicated logic that should be a shared controller, missing theming hooks — aren't bugs in any single component, but become real maintenance costs once a codebase has dozens of components. Periodically revisiting the best-practices and do's/don'ts lessons as your codebase grows helps catch these before they compound.

Common Mistakes

• Debugging a Lit issue from scratch every time instead of checking a consolidated list like this one first.
• Fixing a symptom in one component without checking whether the same root-cause mistake exists elsewhere in the codebase.
• Treating this list as exhaustive rather than as a living reference that grows as you encounter new patterns.
• Not distinguishing between genuine bugs and Shadow DOM's intended encapsulation behavior when something 'doesn't work as expected'.

Key Takeaways

• Most 'component isn't updating' issues trace back to in-place mutation or a missing reactive property declaration.
• Most 'cleanup'/leak issues trace back to a missing disconnectedCallback counterpart for some connectedCallback setup.
• Most 'styling doesn't reach in/out' issues are Shadow DOM encapsulation working as designed, resolved with custom properties or parts.
• A short, consistent debugging checklist resolves the majority of common Lit issues faster than ad hoc investigation.