or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-element.mdcss-styling.mddecorators.mddirectives.mdindex.mdpolyfill-support.mdproperty-system.mdtemplate-system.md
tile.json

tessl/npm-lit-element

A simple base class for creating fast, lightweight web components

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

To install, run

npx @tessl/cli install tessl/npm-lit-element@4.2.0

index.mddocs/

LitElement

LitElement is a simple base class for creating fast, lightweight web components. It extends the Lit project's ReactiveElement with lit-html templating capabilities, providing reactive properties, lifecycle callbacks, scoped CSS styling, and declarative HTML templating for building efficient custom elements.

Package Information

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

Core Imports

import { LitElement, html, css } from "lit-element";

CommonJS:

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

Decorators (for TypeScript):

import { customElement, property, state, query } from "lit-element/decorators.js";

Basic Usage

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

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

  @property({ type: String })
  name = "World";

  @property({ type: Number })
  count = 0;

  render() {
    return html`
      <div class="highlight">
        <h1>Hello, ${this.name}!</h1>
        <p>Count: ${this.count}</p>
        <button @click=${this._increment}>Increment</button>
      </div>
    `;
  }

  private _increment() {
    this.count++;
  }
}

Architecture

LitElement is built on several key architectural components:

  • ReactiveElement Base: Provides reactive property system, lifecycle callbacks, and basic custom element functionality
  • lit-html Integration: Efficient HTML templating with declarative syntax and optimal re-rendering
  • CSS Scoping: Shadow DOM-based styling with scoped CSS and adoptedStyleSheets support
  • Decorator System: TypeScript decorators for enhanced developer experience
  • Property System: Reactive property management with attribute reflection and type conversion
  • Lifecycle Management: Standard custom element lifecycle with additional update phases

Capabilities

Core Element Class

The main LitElement class that extends ReactiveElement with lit-html templating functionality.

class LitElement extends ReactiveElement {
  readonly renderOptions: RenderOptions;
  
  protected createRenderRoot(): Element | ShadowRoot;
  protected update(changedProperties: PropertyValues): void;
  protected render(): unknown;
  connectedCallback(): void;
  disconnectedCallback(): void;
}

Core Element

Property System

Reactive property management with decorators, type conversion, and change detection for building reactive custom elements.

function property(options?: PropertyDeclaration): PropertyDecorator;
function state(options?: StateDeclaration): PropertyDecorator;

interface PropertyDeclaration {
  type?: TypeHint;
  attribute?: boolean | string;
  reflect?: boolean;
  converter?: AttributeConverter;
  noAccessor?: boolean;
  hasChanged?: HasChanged;
}

Property System

Template System

HTML templating with lit-html providing efficient rendering, event binding, and directive support.

function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
function svg(strings: TemplateStringsArray, ...values: unknown[]): SVGTemplateResult;
function render(value: unknown, container: Element | DocumentFragment, options?: RenderOptions): RootPart;

const nothing: symbol;
const noChange: symbol;

Template System

CSS Styling

Scoped CSS system with shadow DOM support, providing isolated styling and efficient style application.

function css(strings: TemplateStringsArray, ...values: (CSSResult | number)[]): CSSResult;
function unsafeCSS(value: string): CSSResult;

class CSSResult {
  readonly cssText: string;
  readonly strings?: TemplateStringsArray;
  readonly values?: readonly CSSResult[];
}

type CSSResultGroup = CSSResult | CSSResultArray;
interface CSSResultArray extends Array<CSSResultGroup> {}

CSS Styling

Decorators

TypeScript decorators for enhanced development experience with declarative property and element configuration.

function customElement(tagName: string): ClassDecorator;
function property(options?: PropertyDeclaration): PropertyDecorator;
function state(options?: StateDeclaration): PropertyDecorator;
function query(selector: string, cache?: boolean): PropertyDecorator;
function queryAll(selector: string): PropertyDecorator;

Decorators

Directives

Built-in directives for advanced templating patterns, conditional rendering, and performance optimization.

function repeat<T>(
  items: Iterable<T>,
  keyFn: KeyFn<T>,
  template: ItemTemplate<T>
): DirectiveResult<typeof RepeatDirective>;

function classMap(classInfo: ClassInfo): DirectiveResult<typeof ClassMapDirective>;
function styleMap(styleInfo: StyleInfo): DirectiveResult<typeof StyleMapDirective>;
function when<T, F>(
  condition: boolean,
  trueCase: () => T,
  falseCase?: () => F
): T | F | typeof nothing;

function map<T>(items: Iterable<T>, template: (item: T, index: number) => unknown): DirectiveResult<typeof MapDirective>;
function join<T>(items: Iterable<T>, joiner: unknown): DirectiveResult<typeof JoinDirective>;
function until(promise: Promise<unknown>, ...defaultContent: unknown[]): DirectiveResult<typeof UntilDirective>;
function asyncAppend(asyncIterable: AsyncIterable<unknown>): DirectiveResult<typeof AsyncAppendDirective>;
function asyncReplace(asyncIterable: AsyncIterable<unknown>): DirectiveResult<typeof AsyncReplaceDirective>;

Directives

Polyfill Support

Browser compatibility support for older browsers without native web components support, including ShadyCSS and ShadyDOM integration.

import "lit-element/polyfill-support.js";

Polyfill Support

Types

Core Types

interface PropertyValues extends Map<PropertyKey, unknown> {}

interface RenderOptions {
  host?: object;
  renderBefore?: ChildNode | null;
  isConnected?: boolean;
}

type TypeHint = 
  | typeof String 
  | typeof Number 
  | typeof Boolean 
  | typeof Array 
  | typeof Object;

interface HasChanged {
  (value: unknown, oldValue: unknown): boolean;
}

interface AttributeConverter<Type = unknown, TypeHint = unknown> {
  fromAttribute?(value: string | null, type?: TypeHint): Type;
  toAttribute?(value: Type, type?: TypeHint): unknown;
}

interface ReactiveController {
  hostConnected?(): void;
  hostDisconnected?(): void;
  hostUpdate?(): void;
  hostUpdated?(): void;
}

interface ReactiveControllerHost {
  addController(controller: ReactiveController): void;
  removeController(controller: ReactiveController): void;
  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: object): void;
  readonly updateComplete: Promise<boolean>;
}