or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-components.mdcustom-directives.mddom-query-decorators.mdindex.mdproperty-decorators.mdstatic-templates.mdtemplate-directives.md
tile.json

tessl/npm-lit

A library for building fast, lightweight web components

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lit@3.3.x

To install, run

npx @tessl/cli install tessl/npm-lit@3.3.0

index.mddocs/

Lit

Lit is a comprehensive web components library that provides a boilerplate-killing component base class with reactive state management, scoped CSS styling, and a declarative HTML template system. Built on standard web components, it offers developers a fast, lightweight, and expressive framework for building modern web applications with reactive property declarations, customizable update lifecycle, ES2021 syntax support, and extensive directive system for advanced template functionality.

Package Information

  • Package Name: lit
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install lit

Core Imports

import { LitElement, html, css } from "lit";
import { customElement, property, state } from "lit/decorators.js";

For CommonJS (though not recommended for modern usage):

const { LitElement, html, css } = require("lit");

Basic Usage

import { LitElement, html, css } from "lit";
import { customElement, property } from "lit/decorators.js";

@customElement("my-element")
class MyElement extends LitElement {
  @property() name = "World";
  
  static styles = css`
    :host {
      display: block;
      padding: 16px;
      color: blue;
    }
  `;

  render() {
    return html`<h1>Hello, ${this.name}!</h1>`;
  }
}

Architecture

Package Structure: The lit package serves as a convenience wrapper that re-exports functionality from three core packages:

  • @lit/reactive-element: Base reactive element system with property observation
  • lit-html: Template system with html, svg, mathml functions and directives
  • lit-element: Complete component system combining reactive elements with templates

This modular architecture allows for tree-shaking and targeted imports while providing a unified API through the main lit package.

Lit is built around several key components:

  • LitElement Base Class: Core component class providing reactive properties, lifecycle management, and templating
  • Template System: html, svg, and mathml tagged template literals for declarative DOM rendering
  • Reactive Properties: Automatic change detection and re-rendering when properties change
  • Directive System: Extensible template directives for advanced functionality (conditionals, loops, styling, etc.)
  • Decorator API: TypeScript decorators for property declaration, DOM queries, and element definition
  • Static Templates: Compile-time optimized templates for better performance

Capabilities

Core Component System

The foundation of Lit - base classes and template functions for creating reactive web components with declarative templates.

class LitElement extends ReactiveElement {
  render(): TemplateResult | unknown;
  static styles?: CSSResultGroup;
}

function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
function css(strings: TemplateStringsArray, ...values: unknown[]): CSSResult;

Core Components

Property Decorators

TypeScript decorators for defining reactive properties, internal state, and element metadata with automatic change detection and re-rendering.

function customElement(tagName: string): ClassDecorator;
function property(options?: PropertyDeclaration): PropertyDecorator;
function state(): PropertyDecorator;

Property Decorators

DOM Query Decorators

Decorators for querying elements in the component's shadow DOM and slot content with automatic updates when DOM changes.

function query(selector: string): PropertyDecorator;
function queryAll(selector: string): PropertyDecorator;
function queryAssignedElements(options?: QueryAssignedElementsOptions): PropertyDecorator;

DOM Query Decorators

Template Directives

Built-in directives for advanced template functionality including conditional rendering, loops, styling, async operations, unsafe content rendering, and performance optimization.

function when<T, F>(
  condition: boolean,
  trueCase: () => T,
  falseCase?: () => F
): T | F | typeof nothing;

function map<T>(
  items: Iterable<T>,
  f: (value: T, index: number) => unknown
): IterableIterator<unknown>;

function classMap(classInfo: ClassInfo): DirectiveResult;
function styleMap(styleInfo: StyleInfo): DirectiveResult;

function unsafeHTML(value: string): DirectiveResult;
function unsafeSVG(value: string): DirectiveResult;
function unsafeMathML(value: string): DirectiveResult;
function templateContent(templateElement: HTMLTemplateElement): DirectiveResult;

Template Directives

Static Templates

Compile-time optimized templates with static parts for improved performance in production applications.

function html(strings: TemplateStringsArray, ...values: unknown[]): StaticValue;
function unsafeStatic(value: string): StaticValue;
function literal(strings: TemplateStringsArray, ...values: unknown[]): StaticValue;

Static Templates

Custom Directives

API for creating custom directives to extend template functionality with reusable template logic and stateful behavior.

function directive<T extends DirectiveClass>(directiveClass: T): DirectiveFn<T>;

class Directive {
  constructor(partInfo: PartInfo);
}

class AsyncDirective extends Directive {
  setValue(value: unknown): void;
}

Custom Directives

Types

Core Types

interface TemplateResult {
  _$litType$: 1 | 2 | 3;
  strings: TemplateStringsArray;
  values: readonly unknown[];
}

interface CSSResult {
  cssText: string;
  toString(): string;
}

type CSSResultGroup = CSSResult | CSSResult[];

interface PropertyDeclaration<Type = unknown> {
  attribute?: boolean | string;
  type?: TypeHint;
  converter?: AttributeConverter<Type>;
  reflect?: boolean;
  hasChanged?(value: Type, oldValue: Type): boolean;
}

Directive Types

interface DirectiveResult<T extends DirectiveClass = DirectiveClass> {
  _$litDirective$: T;
  values: DirectiveParameters<InstanceType<T>>;
}

interface PartInfo {
  readonly type: PartType;
  readonly name?: string;
  readonly strings?: ReadonlyArray<string>;
}

enum PartType {
  ATTRIBUTE = 1,
  CHILD = 2,
  PROPERTY = 3,
  BOOLEAN_ATTRIBUTE = 4,
  EVENT = 5,
  ELEMENT = 6
}