Top-Level API

render

The entry point of every application starts with the render function.

interface render(
	element: any
	target: string|object
	callback?: function
): thenable

The function returns a PromiseLike "thenable" object that is resolved once rendering has succesfully completed; The callback argument is optional and serves a similar purpose.

await render('Hello', document)

createElement

Create a virtual element also known as a snapshot.

interface createElement(
	type: string|function|object
	props?: object
	...children?: any
): object

The return value is the snapshot of an element that describes the state of the user interface at the time. The h function serves as an alias to createElement and vice-versa.

const example = h('h1', {}, 'Hello')

cloneElement

Clone a virtual element, properties are shallow merged while new children replace old.

interface cloneElement(
	element: object
	props?: object
	...children?: any
): object

The return value is itself a virtual element.

const example = cloneElement(h('h1', {}, 'Hello'), {}, 'World')

isValidElement

Validate that the argument is of a valid virtual element.

interface isValidElement(
	element: any
): boolean

The return value indicates with a boolean whether the argument is a virtual element.

const example = isValidElement(h('h1', {}, 'Hello'))

Children

The Children interface provides usefull helpers to use with the opaque props.children data structure.

toArray

Converts children to an array.

interface toArray(
	children: any
): Array<any>

forEach

Iterates through all the children, calling the provided callback with each child.

interface forEach(
	children: any
	callback: function
): void

map

Iterates through all the children, calling the provided callback with each child, the result of which is allocated in the resulting array.

interface map(
	children: any
	callback: function
): Array<any>

count

Returns a count of the number of children.

interface count(
	children: any
): number

filter

Filters through children using the provided callback as a comparator. The result is an array of children that have passed the test.

interface filter(
	children: any
	callback: function
): Array<any>

find

Filters through children to find the first match signaled by the provided comparator callback.

interface find(
	children: any
	callback: function
): any

Portal

A type representative of a portal element.

The "Portal" is a type used to create virtual "portal" elements. Its children are rendered into the target prop provided.

interface Props(
	target: string|object
)

When the portals target changes it's children are re-parented to the new target. The target argument is optionally a "selector".

function Provider ({children}) {
	return h(Portal, {target: 'main'}, ...children)
}

Context

A type representative of a context element, used to create virtual "context" elements. Its children independent of depth can access the provided context value through useContext.

function Provider ({children}) {
	return h(Context, {value: any?}, ...children)
}

"Consumer" is term used to group any decendent component that makes use of the context value.

All consumers are updated when the context value itself changes during an update.

Fragment

The Fragment is a host type used to create virtual "fragment" elements. Its children are rendered without the need for wrapper elements.

const example = h(Fragment, {}, ...children)

Boundary

The Boundary is a componente type used to designate virtual error boundaries. It accepts a fallback prop that is used when it's decendents raise an exception.

interface Props {
	fallback: any
}

When its fallback prop is a function it recievies the "Exception" object as props.

interface Exception {
	message: any
	stack: string
	type: string
}

The exception object can optionally be used directly as a reducers dispatch payload.

const example = h(Boundary, {
	fallback: error => JSON.stringify(error)
}, ...children)

Suspense

The Suspense component is used to create virtual suspense boundary. It accepts a fallback prop that is used when any of its decendents raise a suspend signal(thrown thenable) which in turn transitions it into a suspended state.

interface Props {
	fallback: any
}

The boundary is resumed once all its decendents have settled.

const example = h(Suspense, {
	fallback: 'Loading...'
}, ...children)

Related lazy and useResource work in conjunction with suspense boundaries.

Lazy

Defines a component that is loaded dynamically.

interface lazy (
	render: () => thenable
): function

This can reduce the size of a bundle payload when loading components that aren’t used during the initial render.

const Example = lazy(() => import('./Example.js'))

The return value is itself a component function.

memo

When a component renders the same result given the same props, wrapping it in memo to memoize the result can come with some performance benefits where applicable.

"memo" is short for memoization.

interface memo (
	render: function => any
	compare?: function => boolean
): function

By default memo will shallow compare props.

const Example = memo(props => 'Hello')

To control the comparison, provide a custom comparison function as the second optional argument.

const Example = memo(props => 'Hello', (prev, next) => true)

The comparison function returns a true when the memorize values are equal

The return value is itself a component function.