---

name: lit-best-practices description: Lit web components best practices and performance optimization guidelines. Use when writing, reviewing, or refactoring Lit web components. Triggers on tasks involving Lit components, custom elements, shadow DOM, reactive properties, or web component performance. license: MIT author: community version: 1.0.0

Lit Web Components Best Practices

Best practices for building Lit web components, optimized for AI-assisted code generation and review.

When to Use

Reference these guidelines when:

• Writing new Lit web components
• Implementing reactive properties and state
• Reviewing code for performance or accessibility issues
• Refactoring existing Lit components
• Optimizing rendering and update cycles

Rule Categories

| Category | Rules | Focus | |----------|-------|-------| | 1. Component Structure | 4 rules | Properties, state, TypeScript | | 2. Rendering | 5 rules | Templates, directives, derived state | | 3. Styling | 4 rules | Static styles, theming, CSS parts | | 4. Events | 3 rules | Custom events, naming, cleanup | | 5. Lifecycle | 4 rules | Callbacks, timing, async | | 6. Accessibility | 3 rules | ARIA, focus, forms | | 7. Performance | 4 rules | Updates, caching, lazy loading |

Priority Levels

| Priority | Description | Action | |----------|-------------|--------| | CRITICAL | Major correctness or accessibility issues | Fix immediately | | HIGH | Significant maintainability/performance impact | Address in current PR | | MEDIUM | Best practice violations | Address when touching related code | | LOW | Style preferences, micro-optimizations | Consider during refactoring |

Rules Index

1. Component Structure

• rules/1-1-use-decorators.md - Use TypeScript Decorators (HIGH)
• rules/1-2-separate-state.md - Separate Public Properties from Internal State (HIGH)
• rules/1-3-reflect-sparingly.md - Reflect Properties Sparingly (MEDIUM)
• rules/1-4-default-values.md - Always Provide Default Values (HIGH)

2. Rendering

• rules/2-1-pure-render.md - Keep render() Pure (CRITICAL)
• rules/2-2-use-nothing.md - Use nothing for Empty Content (MEDIUM)
• rules/2-3-use-repeat.md - Use repeat() for Keyed Lists (HIGH)
• rules/2-4-use-cache.md - Use cache() for Conditional Subtrees (MEDIUM)
• rules/2-5-derived-state.md - Compute Derived State in willUpdate() (HIGH)

3. Styling

• rules/3-1-static-styles.md - Always Use Static Styles (CRITICAL)
• rules/3-2-host-styling.md - Style the Host Element Properly (HIGH)
• rules/3-3-css-custom-properties.md - CSS Custom Properties for Theming (MEDIUM)
• rules/3-4-css-parts.md - CSS Parts for Deep Styling (MEDIUM)

4. Events

• rules/4-1-composed-events.md - Dispatch Composed Events (CRITICAL)
• rules/4-2-event-naming.md - Event Naming Conventions (MEDIUM)
• rules/4-3-cleanup-listeners.md - Clean Up Event Listeners (HIGH)

5. Lifecycle

• rules/5-1-super-call-order.md - Correct super() Call Order (CRITICAL)
• rules/5-2-first-updated.md - Use firstUpdated for DOM Operations (HIGH)
• rules/5-3-will-update.md - Use willUpdate for Derived State (HIGH)
• rules/5-4-update-complete.md - Async Operations with updateComplete (MEDIUM)

6. Accessibility

• rules/6-1-delegates-focus.md - delegatesFocus for Interactive Components (HIGH)
• rules/6-2-aria-attributes.md - ARIA for Custom Interactive Components (CRITICAL)
• rules/6-3-form-associated.md - Form-Associated Custom Elements (HIGH)

7. Performance

• rules/7-1-has-changed.md - Custom hasChanged for Complex Types (HIGH)
• rules/7-2-batch-updates.md - Batch Property Updates (MEDIUM)
• rules/7-3-lazy-loading.md - Lazy Load Heavy Dependencies (HIGH)
• rules/7-4-memoization.md - Memoize Expensive Computations (MEDIUM)

Quick Reference

Essential Imports

// Core
import { LitElement, html, css, nothing } from 'lit';
import { customElement, property, state, query } from 'lit/decorators.js';

// Common Directives
import { repeat } from 'lit/directives/repeat.js';
import { cache } from 'lit/directives/cache.js';
import { classMap } from 'lit/directives/class-map.js';
import { until } from 'lit/directives/until.js';

Component Skeleton

@customElement('my-component')
export class MyComponent extends LitElement {
  static styles = css`
    :host { display: block; }
    :host([hidden]) { display: none; }
  `;

  @property({ type: String }) value = '';
  @property({ type: Boolean, reflect: true }) disabled = false;
  @state() private _internal = '';

  render() {
    return html`<slot></slot>`;
  }
}

Resources

• Lit Documentation
• Open Web Components
• Lion Web Components
• web.dev Custom Elements Best Practices