API Reference

Functions

createElement

Creates an element with the specified tag, props and children. This function is typically used as a target for JSX transpilers, rather than called directly.

Parameters:

Return Value:

An element.

isElement

Parameters:

Return Value:

A boolean which indicates the value passed in is a Crank Element.

cloneElement

Clones the passed in element. Throws a TypeError if the value passed in is not an element.

Parameters:

Return Value:

A copy of the element passed in.

Classes

Element

Elements are the basic building blocks of Crank applications. They are JavaScript objects which are interpreted by renderers to produce and manage stateful nodes.

Methods:

constructor

Constructs an element. Typicially, you would use the createElement function rather than calling this constructor directly.

Parameters:

Renderer

An abstract class which is subclassed to render to different target environments. This class is responsible for kicking off the rendering process, caching previous trees by root, and creating/mutating/disposing the nodes of the target environment.

NOTE: The internal Crank renderer methods and type parameters are documented in the guide on custom renderers.

Methods:

constructor

Creates a new Renderer. The base Renderer constructor accepts no parameters.

Renderer.prototype.render

Parameters:

Context

A class which is instantiated and passed to every component function as its this value.

Type Parameters:

Properties:

Methods:

Context.prototype[Symbol.iterator]

Returns an iterator of the props passed to the component. Only used in generator components.

Context.prototype[Symbol.asyncIterator]

Returns an async iterator of the props passed to the component. Only used in generator

Context.prototype.refresh

Updates the component in place.

Context.prototype.schedule

Executes the passed in callback when the component renders. The schedule method will only fire once for each call and callback.

Parameters:

Context.prototype.cleanup

Executes the passed in callback when the component unmounts. The cleanup method will only fire once for each call and callback.

Parameters:

Context.prototype.addEventListener

Adds an event listener to the context. The addEventListener method will also attach event listeners to the underlying top-level node or nodes which were created for the component.

Parameters:

Context.prototype.removeEventListener

Removes an event listener by type, listener and capture option.

Parameters:

Context.prototype.dispatchEvent

Dispatches an event on the context. Will propagate to parent contexts according to the same event bubbling and capture algorithms used by the DOM.

Parameters:

Return Value:

The return value is false if the event is cancelable and an event listener calls the preventDefault method on the event, and true otherwise.

Context.prototype.consume

Retrieves a provision set by an ancestor by key.

Parameters:

Return Value:

The provision by key, or undefined if no provision is found.

Context.prototype.provide

Sets a provision by key for descendant components.

Parameters:

Types

Tag

A type which represents all valid values which can be used for the tag of an element.

Example:

let tag: Tag;

// VALID ASSIGNMENTS
tag = "div";
tag = Symbol("div");
function MyComponent() {
}
tag = MyComponent;

// INVALID ASSIGNMENTS
// @ts-expect-error
tag = 1;
// @ts-expect-error
tag = {};

TagProps

A helper type to map the tag of an element to its expected props.

Type Parameters:

Example:

function Greeting({name}: {name: string}) {
  return <div>Hello {name}</div>
}

let props: TagProps<typeof Greeting>;

// VALID ASSIGNMENTS
props = {name: "Alice"};

// INVALID ASSIGNMENTS
// @ts-expect-error
props = {name: 1000};

Child

A type which describes all valid singular values of an element tree.

Example:

let child: Child;

// VALID ASSIGNMENTS
child = "hello";
child = 1;
child = true;
child = false;
child = null;
child = undefined;
child = <div>Hello</div>;

// INVALID ASSIGNMENTS
// @ts-expect-error
child = [<div>Hello</div>, <div>World</div>];
// @ts-expect-error
child = {};
// @ts-expect-error
child = new Promise(() => {});
// @ts-expect-error
child = new RegExp("Hello");
// @ts-expect-error
child = Symbol("Hello");

Children

A type which describes all valid values of an element tree, including arbitrarily nested iterables of such values.

Example:

let children: Children;

// VALID ASSIGNMENTS
children = "hello";
children = 1;
children = true;
children = false;
children = null;
children = undefined;
children = <div>Hello</div>;
children = [<div>Hello</div>, <div>World</div>];
children = new Set([<div>Hello</div>, <div>World</div>]);

// INVALID ASSIGNMENTS
// @ts-expect-error
children = {};
// @ts-expect-error
children = new RegExp("Hello");
// @ts-expect-error
children = Symbol("Hello");

Component

A type which represents all functions which can be used as a component.

Type Parameters:

ElementValue

A helper type which repesents all the possible rendered values of an element.

Type Parameters:

EventMap

An interface which maps Event type strings to event subclasses. Can be extended via TypeScript module augmentation for strongly typed event listeners.

Example:

declare global {
  module "@bikeshaving/crank" {
    interface EventMap {
      click: MouseEvent;
    }
  }
}

ProvisionMap

An interface which can be extended to provide strongly typed provisions. See Context.prototype.provide and Context.prototype.consume.

Example:

declare global {
  module "@bikeshaving/crank" {
    interface ProvisionMap {
      greeting: string;
    }
  }
}

Special Tags

Fragment

A special element tag for grouping multiple children within a parent.

Copy

A special element tag which copies whatever child appeared previously in the element’s position.

Portal

A special element tag for creating a new element subtree with a different root, passed via the root prop.

Props:

Raw

A special element tag for injecting raw nodes into an element tree via its value prop.

Props: