API reference · Ajo docs

This page lists every export declared in the TypeScript definitions of the ajo package, version 0.1.35, with its signature. The entry points are ajo, ajo/context, ajo/html and the JSX runtime, ajo/jsx-runtime with its twin ajo/jsx-dev-runtime. Types are imported from ajo with import type.

ajo

Export	Signature	Description
`render`	`render(h: Children, el: ParentNode, child?: ChildNode \| null, ref?: ChildNode \| null): void`	Reconciles the children of `el` with `h`, from `child` (default: `el.firstChild`) up to, but not including, `ref` (default: the end). Nodes outside that range are not touched.
`stateful`	`stateful<TArgs extends Args, TTag extends string = DefaultTag>(fn: (this: Host<ElementType<TTag>, TArgs>, args: TArgs) => Iterator<Children>, is?: TTag): Stateful<TArgs, TTag>`	Sets `fn.is` when a tag is given and returns `fn` itself, typed so that `this` is the host of that tag.
`defaults`	`{ tag: string }`	The host tag for stateful components without `is`. Starts as `'div'`.

render(null, el) empties el and ends the stateful components that were inside it. Calling render again on the same container updates it in place.

Changing the default host tag

The browser and server renderers each read their own defaults, so change both, before rendering. To make the types follow, augment the Defaults interface; Stateful then types this with the new element by default.

src/defaults.ts

import { defaults } from 'ajo'
import { defaults as serverDefaults } from 'ajo/html'

defaults.tag = 'section'
serverDefaults.tag = 'section'

declare module 'ajo' {
  interface Defaults { tag: 'section' }
}

ajo/context

Export	Signature	Description
`context`	`context<T>(fallback?: T): { (): T; <V extends T>(value: V): V }`	Creates a context. Call the result without arguments to read the nearest value, or with a value to write it for the calling component and its descendants; a write returns the value. Reads return `fallback` when neither the component nor an ancestor wrote one.
`current`	`current(): Host<object, any> \| null`	The stateful component whose render is in progress, or null. During server rendering it is the protocol-only host.

Context functions only work during a render. Outside one, a read returns the fallback and a write is ignored. See Context.

ajo/html

Export	Signature	Description
`render`	`render(h: Children): string`	Renders to an HTML string.
`html`	`html(h: Children, emit: (chunk: string) => void): void`	Renders to HTML chunks, calling `emit` with each one in document order.
`defaults`	`{ tag: string }`	The host tag for stateful components during server rendering, and the tag that replaces an invalid tag name. Starts as `'div'`.

Both functions are synchronous. Stateful components run once and are finished right after; see Server rendering for the output rules.

ajo/jsx-runtime

The compiler imports these when the JSX import source is ajo; application code rarely calls them. ajo/jsx-dev-runtime exports the same functions.

Export	Signature	Description
`jsx`	`jsx(type: Type, args: Args \| null, key?: string \| number): VNode`	Creates an element. The args object becomes the element: `nodeName` and `key` are added to it.
`jsxs`, `jsxDEV`	Same as jsx.	The names the compiler uses for static children and development builds.
`Fragment`	`Fragment({ children }): children`	Returns its children; the target of `<>…</>`.
`JSX`	Namespace	`IntrinsicElements`, `ElementChildrenAttribute` and `LibraryManagedAttributes` for type-checking JSX.

TSX

import { jsx } from 'ajo/jsx-runtime'

jsx('button', { class: 'save', children: 'Save' }) // the same as <button class="save">Save</button>

The stateful host

Inside a stateful component, this is the host: a DOM element, typed from the component’s tag, with these members added. A ref on the component receives the same object.

Member	Type	Description
`[Symbol.iterator]()`	`Iterator<TArgs>`	Yields the live args object on every iteration. `for…of this` uses it.
`signal`	`AbortSignal`	Aborts when the component ends. Each run of the generator gets a new one.
`next`	`(): undefined`	Renders the component again.
`next`	`<R>(fn: (this: Host, args: TArgs) => R): R`	Calls `fn` with the current args, renders again and returns what `fn` returned. Does nothing when the host is not connected or is ending; does not render re-entrantly.
`throw`	`(value?: unknown) => void`	Throws value into this component, then into its ancestors, until one catches it; rethrows it if none does.
`return`	`(deep?: boolean) => void`	Ends the generator: `finally` blocks run and the signal aborts. `deep` defaults to `true` and ends stateful descendants too; `false` ends only this component.

During server rendering, the host is not an element: it only has the iterator, signal, next, return and throw. There, next and return do nothing and throw rethrows immediately.

Component properties

Property	Type	Description
`is`	`TTag`	The host tag. Optional when `TTag` is the default tag, required otherwise.
`attrs`	`Partial<PropertySetter<TTag> & CommonAttrs> & Args`	Default host attributes and `set:` properties. An `attr:` value written in JSX replaces the default of the same name.
`args`	`Partial<TArgs>`	Default args, overridden by the args written in JSX.

Special attributes

Attribute	Type	On an element	On a stateful component
`key`	`string \| number`	Identifies it among its siblings.	Identifies the host.
`memo`	`unknown`	Skips updates while unchanged: an array is compared item by item, any other value with `===`; `memo` alone renders once.	The same, for renders of the parent.
`skip`	`boolean`	Ajo leaves its children alone.	The component does not render.
`ref`	`(el: TElement \| null) => void`	Receives the element, and null when it is removed.	Receives the host, and null when it is removed.
`set:name`	The property’s type	Assigns the DOM property.	Assigns the DOM property on the host.
`attr:name`	`unknown`	Not special on elements.	Sets an HTML attribute on the host.

class and style accept string | boolean | null, and xmlns a string. On a stateless component, every name, special or not, is an ordinary arg.

Types

Type	Definition
`Stateless<TArgs = {}>`	`(args: TArgs) => Children`
`Stateful<TArgs = {}, TTag = DefaultTag>`	A function with `this: Host<ElementType<TTag>, TArgs>` that takes `TArgs` and returns `Iterator<Children>`, plus `is`, `attrs` and `args`.
`Component<TArgs = {}>`	`Stateless<TArgs> \| Stateful<TArgs>`
`Host<TElement = HTMLElement, TArgs = Args>`	The element type combined with the host members above. Written for cloves.
`WithChildren<T = {}>`	`T` with an optional `children`.
`Children`	`unknown`: anything renderable.
`Args`	`Record<string, unknown>`
`VNode`	`{ nodeName: Type; children?: Children; [key: string]: unknown }`
`Type`	A tag name, any string, a `Stateless` or a `Stateful`.
`Tag`	`keyof (HTMLElementTagNameMap & SVGElementTagNameMap)`
`ElementType<TTag>`	The DOM element type for an HTML or SVG tag; `object` for any other.
`SpecialAttrs<TElement>`	`key`, `skip`, `memo`, `ref` and `children`.
`PropertySetter<TTag>`	A `set:name` entry for every property of the tag’s element type.
`AttrSetter`	Any `attr:${string}` name.
`CommonAttrs`	`class`, `style` and `xmlns`.
`StatefulArgs<TArgs, TTag>`	What JSX accepts on a stateful component: special attributes, with `ref` receiving the host, `set:` properties, `attr:` names and its args.
`ElementChildrenAttribute`	`{ children: Children }`
`HTMLIntrinsicElements`, `IntrinsicElements`	The JSX element table: for every `Tag`, its `set:` properties, special attributes, common attributes and any other attribute.
`ManagedAttributes<C, P>`	Selects `StatefulArgs` for generator components and `P` for the rest. Used as `JSX.LibraryManagedAttributes`.
`Defaults`, `DefaultTag`	An interface to augment, and the tag it yields: `Defaults['tag']` when set, `'div'` otherwise.

Component args must be assignable to Args, so declare them with a type alias rather than an interface.

Source of truth: README.md in cristianfalcone/ajo