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
• Lifecycle Hooks: OnMount, OnUpdate, OnUnmount for fine-grained control

📦 Installation

go get github.com/tinywasm/dom

⚡ Quick Start

For a complete example including Elm architecture (Dynamic Components) and Static Components, check the following file:

👉 web/client.go

This file contains the reference implementation used for testing and demonstrations.

🎨 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").
			On("click", 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:

See the implementation examples in web/client.go to see both approaches in action.

🧩 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 cleanup, ensuring all event listeners are cleaned up when a parent is replaced.

🎯 Event Handling

Event handling is integrated directly into the Builder API via On(eventType, handler).

🔧 Core API

Package Functions

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

// 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.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