Build components without leaving the platform behind.

01 · Start

Install

pnpm add @gottheflag/ion

Ion exposes separate entry points so optional subsystems stay explicit and bundlers can remove unused code.

02 · Component

Your first component

import {
	Component,
	Ion
} from "@gottheflag/ion";

import {
	state
} from "@gottheflag/ion/decorators";

import {
	html
} from "@gottheflag/ion/template";

@Ion.create("x-counter")
class Counter extends Component {
	@state
	private count = 0;

	protected override created() {
		this.on(
			"click",
			"#increment",
			() => {
				this.count++;
			}
		);
	}

	protected override render() {
		return html`
			<button id="increment">
				Count: ${this.count}
			</button>
		`;
	}
}

03 · Registration

Ion.create()

Register while declaring the class:

@Ion.create("x-panel")
class Panel extends Component {}

Or register later:

class Panel extends Component {}

Ion.create(
	Panel,
	"x-panel"
);

Shadow root options

@Ion.create(
	"x-dialog",
	{
		root: {
			mode: "open",
			delegatesFocus: true
		}
	}
)
class Dialog extends Component {}

04 · Lifecycle

A clean component cycle

protected override created() {
	this.on(
		window,
		"resize",
		() => {
			this.requestRender();
		}
	);
}

Listeners registered through this.on() belong to the current component lifetime and are released automatically on a real detach.

05 · Rendering

Templates

protected override render() {
	return html`
		<h2>${this.title}</h2>
		<ul>
			${this.items.map(
				item => html`<li>${item}</li>`
			)}
		</ul>
	`;
}

06 · Reactivity

@state

Use state for internal reactive values. A changed value requests a render; writing the same value again is ignored through Object.is.

@state
private open = false;

toggle() {
	this.open = !this.open;
}

07 · Public state

@property()

@property({
	type: Number,
	reflect: true,
	render: true
})
value = 0;

@property({
	attribute: "busy",
	type: Boolean
})
loading = false;

08 · Events

Own listeners and emit typed events

Delegated event

this.on(
	"click",
	"[data-remove]",
	(event, matched) => {
		matched.remove();
	}
);

Explicit target

this.on(
	window,
	"keydown",
	event => {
		if (event.key === "Escape") {
			this.close();
		}
	}
);

Typed custom event

declare global {
	interface HTMLElementEventMap {
		"counter:change":
			CustomEvent<{
				value: number;
			}>;
	}
}

this.emit(
	"counter:change",
	{
		value: this.count
	}
);

Custom events bubble and cross the shadow boundary by default. Override bubbles, composed, or cancelable when needed.

09 · DOM state

Queries and watchers

@query

@query("#search")
private search:
	HTMLInputElement | null = null;

@query(".row", {
	all: true
})
private rows:
	HTMLElement[] = [];

Query properties are refreshed after every render. They are snapshots of the current rendered DOM.

@watch

@watch("mode")
private modeChanged(
	oldValue: string | null,
	newValue: string | null
) {
	console.log(
		oldValue,
		newValue
	);
}

10 · Styling

Constructable stylesheets

Define styles as a CSS string, a CSSStyleSheet, or an array containing both.

protected static override styles = `
	:host {
		display: block;
	}

	button {
		border-radius: 0.5rem;
	}
`;

11 · Small tools

Cache and once

@cache
get expensiveValue() {
	return compute();
}

@once
initialize() {
	connect();
}

12 · Extension

Plugins

Plugins are optional. Import the plugin entry point only when the application needs the plugin runtime.

import {
	Plugin
} from "@gottheflag/ion/plugin";

class MetricsPlugin
	extends Plugin<
		Panel,
		{
			label: string;
		}
	> {

	get label() {
		return this.options.label;
	}

	protected afterRender() {
		console.log(
			"rendered",
			this.host
		);
	}
}

Panel.use(
	MetricsPlugin,
	{
		label: "dashboard"
	}
);

Read a plugin API from an instance with this.plugin(MetricsPlugin). Plugin lifecycle callbacks cover creation, ready, render boundaries, attribute changes, adoption and removal.

13 · Instrumentation

Hooks

Hooks observe lifecycle phases globally or for one component class. They are best suited to instrumentation and cross-cutting extensions.

import {
	hok
} from "@gottheflag/ion/hook";

const handle =
	hok.afterFor(
		Panel,
		"render",
		host => {
			console.log(
				"rendered",
				host
			);
		}
	);

// later
handle.off();

Phases include define, init, create, render, ready, remove, attribute change, adoption, event emission, and plugin installation.

14 · Component API

Helpers

15 · Reference

Import map