dom

tinywasm/dom

Ultra-minimal DOM & event toolkit for Go (TinyGo WASM-optimized).

tinywasm/dom provides a minimalist, WASM-optimized way to interact with the browser DOM in Go, avoiding the overhead of the standard library and syscall/js exposure. It is designed specifically for TinyGo applications where binary size and performance are critical.

🚀 Features

• Elm-Inspired Architecture: Component-local state with explicit updates (Model → Update → View)
• Fluent Builder API: Chainable methods for concise, readable code
• Hybrid Rendering: Choose DSL for dynamic components or string HTML for static ones
• TinyGo Optimized: Avoids heavy standard library packages to keep WASM binaries <500KB
• Direct DOM Manipulation: No Virtual DOM overhead. You control the updates.
• ID-Based Caching: Efficient element lookup and caching strategy
• Memory Safe: Automatic event listener cleanup on Unmount
• Lifecycle Hooks: OnMount, OnUpdate, OnUnmount for fine-grained control

📦 Installation

go get github.com/tinywasm/dom

⚡ Quick Start

Example 1: Dynamic Component (Elm Pattern)

Counter component with state management:

//go:build wasm

package main

import (
	"github.com/tinywasm/dom"
	"github.com/tinywasm/fmt"
)

// Model (state)
type Counter struct {
	*dom.Element
	count int
}

// View (rendering)
func (c *Counter) Render() *dom.Element {
	return dom.Div().
		Class("counter").
		Add(
			dom.Button().
				Text("-").
				OnClick(c.Decrement),
			dom.Span().
				Class("count").
				Text(fmt.Sprint(c.count)),
			dom.Button().
				Text("+").
				OnClick(c.Increment),
		)
}

// Update (state mutations)
func (c *Counter) Increment(e dom.Event) {
	c.count++
	c.Update() // Explicit re-render
}

func (c *Counter) Decrement(e dom.Event) {
	c.count--
	c.Update()
}

// Lifecycle (optional)
func (c *Counter) OnMount() {
	fmt.Println("Counter mounted with ID:", c.GetID())
}

func main() {
	counter := &Counter{Element: dom.Div(), count: 0}
	dom.Render("app", counter)
	select {}
}

Example 2: Static Component (String HTML)

For simple, static content use string HTML (smaller binary):

type Header struct {
	*dom.Element
}

func (h *Header) RenderHTML() string {
	return `<header class="app-header">
		<h1>My Application</h1>
	</header>`
}

func main() {
	header := &Header{Element: &dom.Element{}}
	dom.Render("app", header)
}

🎨 Fluent Builder API

The new fluent API allows chaining for concise, readable code:

dom.Div().
	ID("container").
	Class("flex items-center").
	Add(
		dom.Button().
			Text("Click me").
			OnClick(handleClick),
		dom.Span().
			Text("Hello World"),
	).
	Render("app") // Terminal operation

Available builders: Div(), Span(), Button(), H1(), H2(), H3(), P(), Ul(), Li(), Input(), Form(), A(), Img()

🔄 Lifecycle Hooks

Components can implement optional lifecycle interfaces:

type MyComponent struct {
	*dom.Element
	data []string
}

// Called after component is mounted to DOM
func (c *MyComponent) OnMount() {
	c.data = fetchData()
	c.Update()
}

// Called after re-render (dom.Update)
func (c *MyComponent) OnUpdate() {
	fmt.Println("Component updated")
}

// Called before component is removed
func (c *MyComponent) OnUnmount() {
	// Cleanup resources
}

📝 Component Interface

All components must implement:

type Component interface {
	GetID() string
	SetID(string)
	RenderHTML() string  // OR Render() *Element
	Children() []Component
}

Two rendering options:

1. RenderHTML() string - For static components (smaller binary)
2. Render() *dom.Element - For dynamic components (type-safe, composable)

Components can implement either or both. DOM checks Render() first, falls back to RenderHTML().

🎯 Hybrid Rendering Strategy

Choose the right rendering method for each component:

// Static: Use string HTML
type Footer struct {
	*dom.Element
}
func (f *Footer) RenderHTML() string {
	return `<footer>© 2026 My App</footer>`
}

// Dynamic: Use DSL Builder
type TodoList struct {
	*dom.Element
	todos []string
}
func (t *TodoList) Render() *dom.Element {
	list := dom.Ul() // ID is auto-injected from t.GetID()
	for _, todo := range t.todos {
		list.Add(dom.Li().Text(todo))
	}
	return list
}

🧩 Nested Components

Components can contain child components:

type MyList struct {
	*dom.Element
	items []dom.Component
}

func (c *MyList) Children() []dom.Component {
	return c.items
}

func (c *MyList) Render() *dom.Element {
	list := dom.Div()
	for _, item := range c.items {
		list.Add(item) // Components can be children
	}
	return list
}

When you call dom.Render("app", myList), the library will:

1. Render the HTML
2. Call OnMount() for MyList
3. Recursively call OnMount() for all items

The same recursion applies to Unmount(), ensuring all event listeners are cleaned up.

🎯 Event Handling

func (c *MyComponent) OnMount() {
	root, _ := dom.Get(c.GetID())

	// Reference interface focus on reading and interaction
	root.On("click", func(e dom.Event) {
		id := e.TargetID() // "item-1", "item-2", etc.
		// Handle logic...
	})
}

🔧 Core API

Package Functions

// Rendering
dom.Render(parentID, component)  // Replace parent's content
dom.Append(parentID, component)  // Append after last child
dom.Hydrate(parentID, component) // Attach to server-rendered HTML
dom.Update(component)            // Re-render in place

// Lifecycle
dom.Unmount(component)           // Remove and cleanup

// Element Access (returns Reference interface)
dom.Get(id)                      // Get element by ID
dom.QueryAll(selector)           // Query by CSS selector

// Routing (hash-based)
dom.OnHashChange(handler)        // Listen to hash changes
dom.GetHash()                    // Get current hash
dom.SetHash(hash)                // Set hash

Element Helpers

Embedding *dom.Element provides these methods automatically:

type Counter struct {
	*dom.Element
	count int
}

// Chainable helpers
counter.Update()              // Trigger re-render
counter.Unmount()             // Remove from DOM
counter.GetID()               // Get unique ID
counter.SetID("my-id")        // Set custom ID

📚 Documentation

For more detailed information, please refer to the documentation in the docs/ directory:

1. Specification & Philosophy: Design goals, architecture, and key decisions.
2. API Reference: Detailed definition of DOM, Element, and Component interfaces.
3. Creating Components: Guide to building basic and nested components.
4. Event Handling: Using the Event interface for clicks, inputs, and forms.
5. Advanced Patterns: Dynamic lists, decoupling, and performance tips.
6. Comparison: TinyDOM vs. syscall/js, VDOM, and JS frameworks.

🆕 What's New in v0.2.0

• ✅ Elm-inspired architecture - Component-local state with explicit updates
• ✅ Fluent Builder API - Chainable methods (dom.Div().ID("x").Class("y"))
• ✅ Hybrid rendering - Choose DSL or string HTML per component
• ✅ Lifecycle hooks - OnMount, OnUpdate, OnUnmount
• ✅ Auto-ID generation - All components get unique IDs automatically
• ✅ Smaller binaries - TinyGo-optimized, <500KB for typical apps

📊 Performance

Binary Size (TinyGo WASM):

• Simple counter app: ~35KB (compressed)
• Todo list with 10 components: ~120KB (compressed)
• Full application: <500KB (compressed)

Compared to standard library approach: 60-80% smaller binaries.

License

MIT