Progressive Web Components.

API Reference




namespace, customElements, customElement, COMPONENT_SYMBOL, CONSTRUCTED_SYMBOL, connect, disconnect, DOM, render, Fragment, h, html, css, delegateEventListener, undelegateEventListener, dispatchEvent, dispatchAsyncEvent, defineListeners, property, getProperty, getProperties, defineProperties, defineProperty, isComponent, isComponentConstructor, extend, Component, until




ComponentConstructorInterface, ClassFieldDescriptor, ClassFieldAttributeConverter, ClassFieldPropertyConverter, ClassFieldObserver, ClassFieldValidator, DelegatedEventCallback, DelegatedEventDescriptor, ComponentInterface, IterableNodeList, Template, TemplateItem, HyperNode, TemplateFunction, HyperProperties, TemplateItems, HyperClasses, Context, Observable, Subscription, ClassDescriptor, ClassElement, TemplateFilter, AsyncEvent

class CustomElementRegistry

The CustomElementRegistry interface provides methods for registering custom elements and querying registered elements.


Name Type Readonly Description
native boolean Support native registry.
registry { [key: string]: HTMLElement; } A global registry.
tagNames { [key: string]: string; } A map of tag names.
queue { [key: string]: Array<(value?: any): void>; } Collect "whenDefined" promises.


method get

Get the Custom Element definition for a tag.

(name: string): HTMLElement|undefined


Name Type Optional Description
name string The name of the tag.

Returns: HTMLElement|undefined The definition for the given tag.

method define

Define a new Custom Element.

(name: string, constructor: HTMLElement & { shim?: boolean; }, options?: ElementDefinitionOptions): void


Name Type Optional Description
name string The tag name for the element.
constructor HTMLElement & { shim?: boolean; } The Custom Element constructor.
options ElementDefinitionOptions A set of definition options, like `extends` for native tag extension.

Returns: void

method whenDefined

It returns a Promise that resolves when the named element is defined.

(name: string): Promise<HTMLElement>


Name Type Optional Description
name string The Custom Element name.

Returns: Promise<HTMLElement> A Promise that resolves when the named element is defined.

method upgrade

It upgrades all custom elements in a subtree even before they are connected to the main document.

(root: HTMLElement): void


Name Type Optional Description
root HTMLElement A Node instance with descendant elements that are to be upgraded.

Returns: void

constant namespace


Window & globalThis

constant customElements

The global DNA registry instance.



constant customElement

Decorate and define component classes.


(name: string, options?: ElementDefinitionOptions|undefined): (classOrDescriptor: ComponentConstructorInterface<HTMLElement>|ClassDescriptor): any


A symbol which identify components.


unique Symbol


A symbol which identify constructed components (properties can be assigned).


unique Symbol

constant connect

Invoke connectedCallback method of a Node (and its descendents). It does nothing if life cycle is disabled.


(node: Node, force?: boolean): void

constant disconnect

Invoke disconnectedCallback method of a Node (and its descendents). It does nothing if life cycle is disabled.


(node: Node): void

constant DOM

DOM is a singleton that components uses to access DOM methods. By default, it uses browsers' DOM implementation, but it can be set to use a different one. For example, in a Node context it is possibile to use DNA thanks to the jsdom dom implementation. It also handle element life cycle for custom elements unless otherwise specified.


    createDocumentFragment: (): DocumentFragment;
    createElement<K extends "object"|"link"|"small"|"sub"|"sup"|"track"|"progress"|"a"|"abbr"|"address"|"applet"|"area"|"article"|"aside"|"audio"|"b"|"base"|"basefont"|"bdi"|"bdo"|"blockquote"|"body"|"br"|"button"|"canvas"|"caption"|"cite"|"code"|"col"|"colgroup"|"data"|"datalist"|"dd"|"del"|"details"|"dfn"|"dialog"|"dir"|"div"|"dl"|"dt"|"em"|"embed"|"fieldset"|"figcaption"|"figure"|"font"|"footer"|"form"|"frame"|"frameset"|"h1"|"h2"|"h3"|"h4"|"h5"|"h6"|"head"|"header"|"hgroup"|"hr"|"html"|"i"|"iframe"|"img"|"input"|"ins"|"kbd"|"label"|"legend"|"li"|"main"|"map"|"mark"|"marquee"|"menu"|"meta"|"meter"|"nav"|"noscript"|"ol"|"optgroup"|"option"|"output"|"p"|"param"|"picture"|"pre"|"q"|"rp"|"rt"|"ruby"|"s"|"samp"|"script"|"section"|"select"|"slot"|"source"|"span"|"strong"|"style"|"summary"|"table"|"tbody"|"td"|"template"|"textarea"|"tfoot"|"th"|"thead"|"time"|"title"|"tr"|"u"|"ul"|"var"|"video"|"wbr">(tagName: K, options?: ElementCreationOptions|undefined): HTMLElementTagNameMap[K];
    createElementNS(namespaceURI: string, tagName: string): Element;
    createTextNode: (data: string): Text;
    createComment(data: string): Comment;
    createEvent(typeArg: string, eventInitDict?: CustomEventInit<any>): CustomEvent<any>;
    appendChild<T extends Node>(parent: Node, newChild: T, slot?: boolean): T;
    removeChild<T_1 extends Node>(parent: Node, oldChild: T_1, slot?: boolean): T_1;
    insertBefore<T_2 extends Node>(parent: Node, newChild: T_2, refChild: Node|null, slot?: boolean): T_2;
    replaceChild<T_3 extends Node>(parent: Node, newChild: Node, oldChild: T_3, slot?: boolean): T_3;
    getAttribute(element: Element, qualifiedName: string): string|null;
    hasAttribute(element: Element, qualifiedName: string): boolean;
    setAttribute(element: Element, qualifiedName: string, value: string): void;
    removeAttribute(element: Element, qualifiedName: string): void;

constant render

Render a set of Nodes into another, with some checks for Nodes in order to avoid useless changes in the tree and to mantain or update the state of compatible Nodes.


(input: Template, root?: Node, slot?: boolean): Node|Node[]|void

constant Fragment

A constructor alias used for JSX fragments </>.



constant h

HyperFunction factory to use as JSX pragma.


(tagOrComponent: string|HTMLElement|Fragment|TemplateFunction|Node, properties?: HyperProperties|null, children: TemplateItems): HyperNode

constant html

Compile a template string into virtual DOM template.


(string: string|TemplateStringsArray, values: any[]): Template

constant css

Scope a CSS string, adding a compnent-specific trailing selector to all rules. It also converts :host selectors for cross browser compatibility.


(name: string, cssText: string, extend?: string|undefined): string

constant delegateEventListener

Delegate an Event listener.


(element: Element, eventName: string, selector: string|null, callback: DelegatedEventCallback, options?: AddEventListenerOptions|undefined): void

See also

constant undelegateEventListener

Remove an Event delegation.


(element: Element, eventName: string, selector: string|null, callback: DelegatedEventCallback): void

constant dispatchEvent

Dispatch a custom Event.


(element: Element, event: Event|string, detail?: CustomEventInit<any>|undefined, bubbles?: boolean, cancelable?: boolean, composed?: boolean): boolean

constant dispatchAsyncEvent

Dispatch an async custom Event.


(element: Element, event: Event|string, detail?: CustomEventInit<any>|undefined, bubbles?: boolean, cancelable?: boolean, composed?: boolean): Promise<any[]>

constant defineListeners

Define component constructor listeners.


(constructor: ComponentConstructorInterface<HTMLElement>): void

constant property

A decorator for class fields definition.


(descriptor?: ClassFieldDescriptor): (targetOrClassElement: ComponentInterface<HTMLElement>|ClassElement, propertyKey: string, originalDescriptor?: ClassFieldDescriptor|undefined): any

constant getProperty

Retrieve property descriptor.


(constructor: ComponentConstructorInterface<HTMLElement>, propertyKey: string): ClassFieldDescriptor

constant getProperties

Retrieve all properties descriptors.


(constructor: ComponentConstructorInterface<HTMLElement>): {
    [propertyKey: string]: ClassFieldDescriptor;

constant defineProperties

Define component constructor properties.


(constructor: ComponentConstructorInterface<HTMLElement>): void

constant defineProperty

Define an observed property.


(constructor: ComponentConstructorInterface<HTMLElement>, propertyKey: string, descriptor: ClassFieldDescriptor, symbolKey?: Symbol|undefined, initializer?: Function|undefined): PropertyDescriptor

constant isComponent

Check if a node is a component.


(node: any): node is ComponentInterface

constant isComponentConstructor

Check if a constructor is a component constructor.


(constructor: Function): constructor is ComponentConstructorInterface

constant extend

Get a native HTMLElement constructor to extend by its name.


<T extends {
    constructor(): HTMLElement;
    prototype: HTMLElement;
}>(constructor: T): ComponentConstructorInterface<InstanceType<T>>

constant Component

The DNA base Component constructor, a Custom Element constructor with declarative properties and event delegations, custom template and a complete life cycle implementation. All DNA components must extends this class.



constant until

It renders the template when then provided Thenable is in pending status.


(thenable: Promise<any>, template: Template): Promise<boolean>

enum NamespaceURI

A list of namespaceURI bound with their tagName.

Member Description Value
svg "http://www.w3.org/2000/svg"

type ComponentConstructorInterface

The basic DNA Component interface. It's a Custom Element, but with some extra useful method.

    observedAttributes: string[];
    properties?: {
        [key: string]: ClassFieldDescriptor|Function|Function[];
    listeners?: {
        [key: string]: DelegatedEventCallback|DelegatedEventDescriptor;
    shim?: boolean;
    constructor(node?: HTMLElement, properties?: {
        [key: string]: any;
    }): ComponentInterface<T>;
    constructor(properties?: {
        [key: string]: any;
    }): ComponentInterface<T>;
    constructor(): ComponentInterface<T>;
    prototype: ComponentInterface<T>;

See also

type ClassFieldDescriptor

A list of properties for an class field description.

PropertyDescriptor & {
    name?: PropertyKey;
    attribute?: true|string;
    defaultValue?: any;
    type?: Function|Function[];
    fromAttribute?: ClassFieldAttributeConverter;
    toAttribute?: ClassFieldPropertyConverter;
    observe?: ClassFieldObserver;
    observers?: ClassFieldObserver[];
    validate?: ClassFieldValidator;
    getter?: (value?: any): any;
    setter?: (newValue?: any): any;
    event?: true|string;
    symbol?: Symbol;
    initializer?: Function;

type ClassFieldAttributeConverter

Convert attribute to property value.

(value: string|null): any

type ClassFieldPropertyConverter

Convert property to attribute value.

(value: any): string|null|undefined

type ClassFieldObserver

The observer signature for class fields.

(oldValue: any, newValue: any): any

type ClassFieldValidator

A validation function for the class field.

(value: any): boolean

type DelegatedEventCallback

Describe the signature of a delegated event callback.

(event: Event, target?: Node): any

type DelegatedEventDescriptor

A descriptor for an event delegation.

AddEventListenerOptions & {
    callback: DelegatedEventCallback;

type ComponentInterface

T & {
    is: string;
    [COMPONENT_SYMBOL]: boolean;
    [CONSTRUCTED_SYMBOL]: boolean;
    slotChildNodes: IterableNodeList;
    adoptedStyleSheets?: CSSStyleSheet[];
    constructor: ComponentConstructorInterface<T>;
    initialize(properties?: {
        [key: string]: any;
    }): void;
    connectedCallback(): void;
    disconnectedCallback(): void;
    attributeChangedCallback(attributeName: string, oldValue: null|string, newValue: null|string): void;
    propertyChangedCallback(propertyName: string, oldValue: any, newValue: any): void;
    render(): Template;
    forceUpdate(): void;
    observe(propertyName: string, callback: ClassFieldObserver): void;
    unobserve(propertyName: string, callback: ClassFieldObserver): void;
    dispatchEvent(event: Event): boolean;
    dispatchEvent(event: string, detail?: any, bubbles?: boolean, cancelable?: boolean, composed?: boolean): boolean;
    dispatchAsyncEvent(event: Event): Promise<any[]>;
    dispatchAsyncEvent(event: string, detail?: any, bubbles?: boolean, cancelable?: boolean, composed?: boolean): Promise<any[]>;
    delegateEventListener(event: string, selector: string|null, callback: DelegatedEventCallback): void;
    undelegateEventListener(event?: string, selector?: string|null, callback?: DelegatedEventCallback): void;
    emulateLifeCycle(): void;

type IterableNodeList

Node[] & {
    item(index: number): Node|null;

type Template

A generic template. Can be a single atomic item or a list of items.


type TemplateItem

The atomic template item. It can be a node, a Hyper or Interpolate function or a primitive value.


type HyperNode

A virtual description of a Node, generate by the h helper and used in the render function.

    node?: Node;
    Component?: ComponentConstructorInterface<HTMLElement>;
    Function?: TemplateFunction;
    tag?: string;
    is?: string;
    key?: any;
    isFragment?: boolean;
    isSlot?: boolean;
    namespaceURI?: NamespaceURI;
    properties: HyperProperties;
    children: TemplateItems;

type TemplateFunction

A function that returns a template.

(props: HyperProperties, state: Map<string, any>, update: (): boolean, live: (): boolean, context: Context): Template

type HyperProperties

The properties of a HyperNode.

    is?: string;
    slot?: string;
    key?: any;
    xlmns?: NamespaceURI;
    children?: TemplateItems;
    class?: HyperClasses;
    [key: string]: any;

type TemplateItems

A list of template items.


type HyperClasses

Classes dictionary.

    [key: string]: boolean;

type Context

The node context interface.

    isElement?: boolean;
    isText?: boolean;
    tagName?: string;
    is?: string;
    key?: any;
    props: WeakMap<Context, {
        [key: string]: any;
    state: Map<string, any>;
    childNodes?: IterableNodeList;
    slotChildNodes?: IterableNodeList;
    first?: Node;
    last?: Node;
    function?: TemplateFunction;
    fragments: Context[];
    parent?: Context;
    root?: Context;

type Observable

Observable-like minimal interface.

    pipe(operator: (value: T): any): Observable<T>;
    subscribe(nextCallback: (value: T): any, errorCallback: (error: Error): any, completeCallback: (): any): Subscription;

type Subscription

Subscription-like minimal interface.

    unsubscribe(): void;

type ClassDescriptor

The class descriptor interface.

    kind: 'class';
    elements: ClassElement[];
    finisher?: <T>(constructor: {
        constructor(): T;
    }): undefined|{
        constructor(): T;

type ClassElement

Decorator class element descriptor.

type TemplateFilter

A filter function signature for template items.

(item: Node): boolean

type AsyncEvent

Event & {
    respondWith(callback: (): Promise<any>): void;