Lit Best Practices

Design Components with a Clear, Minimal API

A component's properties, slots, and events together form its public API. The single highest-leverage best practice across everything else in this course is keeping that API small, well-named, and deliberate — every additional property or event is a piece of surface area you (and every consumer) will maintain indefinitely.

Favor several small, focused, well-typed properties over one large configuration object, use @state() for anything genuinely internal, and document every property, slot, and event as carefully as you would a public library function.

// Prefer this: small, focused, self-documenting properties
@property() variant: 'primary' | 'secondary' = 'primary';
@property({ type: Boolean }) disabled = false;
@state() private isPressed = false; // internal only

// Over this: one large, loosely-typed config object
@property({ attribute: false }) config: any = {};

The first version is self-documenting and gives real TypeScript checking; the second hides the actual API surface inside an untyped object.

A Practical Best-Practices Checklist

1. Keep properties minimal, typed, and well-named
2. Use @state() for internal-only reactive fields
3. Keep render() pure — no side effects, no mutation
4. Pair every connectedCallback with matching disconnectedCallback cleanup
5. Use repeat() for reorderable/stateful lists, map() otherwise
6. Expose theming via CSS custom properties, not hardcoded values
7. Test in a real browser environment with accessibility assertions

• Treat this checklist as a code-review reference, not a one-time setup step — revisit it as components evolve.
• Most items map directly to a dedicated lesson earlier in this course, which covers the full reasoning behind each one.
• Prioritize the API design and render() purity items first — they're the hardest to retrofit later.
• Performance and testing practices matter increasingly as a codebase and team grow.

Best Practices by Category

A categorized summary of best practices covered throughout this course.

Consistency Matters More Than Any Single Rule

Individually, most of these practices are small. Their real value compounds when applied consistently across every component in a codebase or design system — a developer moving between components should be able to predict how properties, events, and styling hooks are named and structured, without re-learning conventions component by component.

• Write down your team's conventions (naming, event patterns, theming approach) once, even briefly, rather than relying on tribal knowledge.
• Review new components against the same checklist you'd apply to existing ones.
• Refactor inconsistencies opportunistically rather than in one large, risky pass.

Revisit Best Practices as Lit Evolves

Lit is an actively maintained library, and community conventions (like the Context protocol, or @lit-labs packages graduating to stable) continue to evolve. Treat this checklist as a living reference, and periodically check Lit's official documentation and release notes for updated guidance rather than treating any single lesson as permanently final.

Common Mistakes

• Treating best practices as a one-time setup checklist rather than an ongoing code-review standard.
• Applying different conventions inconsistently across components within the same codebase or design system.
• Prioritizing performance optimization before basic API design and correctness are solid.
• Not revisiting practices periodically as Lit itself and community conventions continue to evolve.

Key Takeaways

• A component's properties, slots, and events form its public API — keep that API small and deliberate.
• render() should stay pure; lifecycle setup and cleanup should always be paired.
• Theming should go through CSS custom properties and parts, not hardcoded values.
• Consistency across an entire codebase matters more than perfecting any single component in isolation.