README
¶
tinywasm/dom
Ultra-minimal DOM & reactivity toolkit for Go (TinyGo WASM-optimized).
tinywasm/dom provides a type-safe, fine-grained reactive engine over the browser DOM for TinyGo/WASM. State lives in typed Signals; changing a signal patches only the bound DOM node — no Virtual DOM, no manual Update() calls, no re-renders.
Features
- Fine-Grained Reactivity:
SignalString/SignalBool/SignalNodes— O(1) surgical patches that preserve focus and IME composition. - Auto-tracking:
BindTextFunc/DeriveStringdiscover dependencies automatically — no explicit dep lists. - Typed builder:
Text,Child,Attr,Class,Set(kv ...fmt.KeyValue)— noAdd(...any). - Two-method contract:
Render() *Element(pure, once per mount) + optionalInit(ctx dom.Ctx)(side effects, once ever). - Keyed lists & conditional subtrees:
BindChildren(SignalNodes)+Show(cond, renderFn). - No Virtual DOM: Zero diffing; nodes are never replaced unless structure truly changes.
- TinyGo Optimized: Zero stdlib;
tinywasm/fmtfor logs; slices over maps;<500KBWASM binaries. - Isomorphic: same
Render()produces correct SSR HTML on backend and live WASM on frontend.
Installation
go get github.com/tinywasm/dom
Quick Start
import (
dom "github.com/tinywasm/dom"
"github.com/tinywasm/fmt"
"github.com/tinywasm/html"
)
type Counter struct {
dom.Element
n int
count *dom.SignalString
}
func (c *Counter) Init(ctx dom.Ctx) {
c.count = dom.NewString("0")
}
func (c *Counter) Render() *dom.Element {
return html.Div(
html.Span().BindText(c.count).Class("count"),
html.Button("Increment").On("click", func(e dom.Event) {
c.n++
c.count.Set(fmt.Sprint(c.n))
}),
)
}
func main() {
d := dom.New(...)
d.Render("app", &Counter{})
}
Component Contract
| Method | Role | Cardinality |
|---|---|---|
Render() *Element |
Pure: state → structure, no side effects | Once per mount |
Init(ctx dom.Ctx) |
Imperative: create signals, load storage, start timers | Exactly once |
Init is optional — only add it when there is setup to do.
Signals
// String cell — UI text, attr, input state
name := dom.NewString("World")
name.Get() // "World"
name.Set("Alice") // notifies all bindings
name.Update(func(v string) string { return v + "!" })
// Bool cell — class/attr toggles, Show conditions
active := dom.NewBool(false)
active.Toggle()
// List of rendered rows — keyed reconcile
rows := dom.NewNodes(elem1, elem2)
rows.Set(newRows)
// Derived (auto-tracking — no deps list)
full := dom.DeriveString(func() string { return first.Get() + " " + last.Get() })
Element Builder
html.Div().
Class("card").
Attr("role", "region").
Child(
html.Span().BindText(name),
html.Input("text").Bind(name), // two-way
html.Button("Save").BindAttrBool("disabled", saving),
)
Binding methods:
| Method | DOM target |
|---|---|
.BindText(s *SignalString) |
textContent |
.BindAttr(name, s) |
attribute value |
.BindClass(class, on) |
class toggle |
.BindAttrBool(name, on) |
boolean attribute (disabled, checked…) |
.Bind(s) |
two-way <input>/<textarea> |
.BindChildren(s *SignalNodes) |
keyed child list |
.BindTextFunc(fn) |
computed text (auto-tracking) |
.Autofocus() |
focus on first appearance |
Structural:
dom.Show(visible, func() *dom.Element { return html.Div(...) }) // mount/unmount subtree
html.Ul().BindChildren(c.rows) // keyed list
Lifecycle
Init (once) → Render → wire bindings & events
signal.Set → patch bound node (O(1))
unmount → run OnCleanup + unsubscribe signals
Mount Point
Always "app", never "body" — Render("body", ...) overwrites innerHTML and destroys the SVG sprite injected by tinywasm/assetmin.
Dev Mode
dom.SetDevMode(true) // enabled at runtime; default false (production no-op)
When on:
- Reactive trace: logs
signal.Set → patch #node-id BindChildrenwarns on duplicate/empty keys- Nil signal / non-input
.Bind/ pointer-embeddedElementemit warnings instead of panicking
Related Packages
- tinywasm/html — HTML element builders (no-arg:
Div(),Span(),Button()…) - tinywasm/svg — SVG builders + icon sprite
- tinywasm/image — Image element builders
Documentation
- docs/ARCHITECTURE.md — component model, builder API, lifecycle
- docs/DESIGN.md — decision record: why signals, no generics, auto-tracking
- docs/BINDING_MODEL.md — mental model with worked examples
- docs/diagrams/lifecycle.md — Mermaid lifecycle flowchart
- docs/TRADEOFFS.md — fine-grained reactivity vs VDOM trade-offs
- AGENTS.md — constraints for agents and contributors
License
MIT
Documentation
¶
Index ¶
- func Append(parentID string, component Component) error
- func GetDocumentAttr(_ string) string
- func GetHash() string
- func Log(v ...any)
- func OnHashChange(handler func(hash string))
- func Render(parentID string, component Component) error
- func SetDevMode(on bool)
- func SetDocumentAttr(_, _ string)
- func SetHash(hash string)
- func SetLog(log func(v ...any))
- type Component
- type Ctx
- type DOM
- type Element
- func (b *Element) Attr(key, val string) *Element
- func (b *Element) Autofocus() *Element
- func (b *Element) Bind(s *SignalString) *Element
- func (b *Element) BindAttr(name string, s *SignalString) *Element
- func (b *Element) BindAttrBool(name string, on *SignalBool) *Element
- func (b *Element) BindAttrBoolFunc(name string, fn func() bool) *Element
- func (b *Element) BindAttrFunc(name string, fn func() string) *Element
- func (b *Element) BindChildren(s *SignalNodes) *Element
- func (b *Element) BindClass(class string, on *SignalBool) *Element
- func (b *Element) BindClassFunc(class string, fn func() bool) *Element
- func (b *Element) BindText(s *SignalString) *Element
- func (b *Element) BindTextFunc(fn func() string) *Element
- func (b *Element) Child(c ...Component) *Element
- func (b *Element) Children() []Component
- func (b *Element) Class(class ...string) *Element
- func (b *Element) For(other *Element) *Element
- func (b *Element) GetID() string
- func (b *Element) ID(id string) *Element
- func (b *Element) Key(key string) *Element
- func (b *Element) NoCloseTag() *Element
- func (b *Element) On(t string, h func(Event)) *Element
- func (b *Element) Render(parentID string) error
- func (b *Element) Set(kv ...fmt.KeyValue) *Element
- func (b *Element) SetID(id string)
- func (b *Element) String() string
- func (b *Element) Text(text string) *Element
- type Event
- type Reference
- type SignalBool
- type SignalNodes
- type SignalString
- type ViewRenderer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Append ¶ added in v0.2.0
Append injects a component AFTER the last child of the parent element.
func GetDocumentAttr ¶ added in v0.9.0
GetDocumentAttr returns an empty string on the backend.
func OnHashChange ¶ added in v0.0.11
func OnHashChange(handler func(hash string))
OnHashChange registers a hash change listener.
func SetDevMode ¶ added in v0.11.0
func SetDevMode(on bool)
SetDevMode enables or disables development mode features.
func SetDocumentAttr ¶ added in v0.9.0
func SetDocumentAttr(_, _ string)
SetDocumentAttr is a no-op on the backend.
Types ¶
type Component ¶
Component is the minimal interface for components. All components must implement this for both SSR (backend) and WASM (frontend).
NOTE: If your struct embeds Element, embed it as a VALUE, not a pointer:
type MyComponent struct {
Element // ✅ Correct — never nil
// NOT: *Element // ❌ Wrong — nil pointer causes panic in renderToHTML
}
This is because renderToHTML calls GetID() on every Component child before checking ViewRenderer.
type Ctx ¶ added in v0.11.0
type Ctx interface {
OnCleanup(fn func())
}
Ctx is handed to the Init hook. Register teardown for async resources (timers, websockets).
type DOM ¶
type DOM interface {
// Render injecta un componente en un elemento padre.
// 1. Llama a componente.Init(ctx) si existe (una sola vez)
// 2. Llama a componente.Render() para obtener el árbol de elementos
// 3. Inyecta el HTML resultante y enlaza bindings y eventos
Render(parentID string, component Component) error
// Append injecta un componente DESPUÉS del último hijo del elemento padre.
// Útil para listas dinámicas.
Append(parentID string, component Component) error
// OnHashChange registra un listener para cambios en el hash de la URL.
OnHashChange(handler func(hash string))
// GetHash devuelve el hash actual de la URL (ej. "#help").
GetHash() string
// SetHash actualiza el hash de la URL.
SetHash(hash string)
// Get retrieves an element by ID.
Get(id string) (Reference, bool)
// Log provides logging functionality using the log function passed to New.
Log(v ...any)
}
DOM is the main entry point for interacting with the browser. It is designed to be injected into your components.
type Element ¶
type Element struct {
// contains filtered or unexported fields
}
Element represents a DOM element in the fluent Element API.
func NewElement ¶ added in v0.10.1
NewElement creates an Element with the given HTML tag. Used by tinywasm/html, tinywasm/svg, tinywasm/image to build elements.
func Show ¶ added in v0.11.0
func Show(cond *SignalBool, render func() *Element) *Element
Show is implemented for SSR.
func (*Element) Autofocus ¶ added in v0.11.0
Autofocus marks the element to be focused when it first appears.
func (*Element) Bind ¶ added in v0.11.0
func (b *Element) Bind(s *SignalString) *Element
Bind provides two-way binding for <input> and <textarea>.
func (*Element) BindAttr ¶ added in v0.11.0
func (b *Element) BindAttr(name string, s *SignalString) *Element
BindAttr links an attribute to a SignalString.
func (*Element) BindAttrBool ¶ added in v0.11.0
func (b *Element) BindAttrBool(name string, on *SignalBool) *Element
BindAttrBool toggles a boolean attribute (disabled, checked, etc.) based on a SignalBool.
func (*Element) BindAttrBoolFunc ¶ added in v0.11.0
BindAttrBoolFunc toggles a boolean attribute based on a computed boolean.
func (*Element) BindAttrFunc ¶ added in v0.11.0
BindAttrFunc links an attribute to a computed string.
func (*Element) BindChildren ¶ added in v0.11.0
func (b *Element) BindChildren(s *SignalNodes) *Element
BindChildren links a container's children to a SignalNodes.
func (*Element) BindClass ¶ added in v0.11.0
func (b *Element) BindClass(class string, on *SignalBool) *Element
BindClass toggles a class based on a SignalBool.
func (*Element) BindClassFunc ¶ added in v0.11.0
BindClassFunc toggles a class based on a computed boolean.
func (*Element) BindText ¶ added in v0.11.0
func (b *Element) BindText(s *SignalString) *Element
BindText links the element's textContent to a SignalString.
func (*Element) BindTextFunc ¶ added in v0.11.0
BindTextFunc links the element's textContent to a computed string.
func (*Element) Children ¶ added in v0.2.3
Children returns the component's children (components only).
func (*Element) For ¶ added in v0.8.0
For sets the for= attribute pointing to other's ID, auto-generating other's ID if it has none. Use for label/input pairing and aria-* references.
func (*Element) Key ¶ added in v0.11.0
Key sets a stable identity for keyed reconciliation in BindChildren.
func (*Element) NoCloseTag ¶ added in v0.10.1
NoCloseTag marks the element as self-closing (no closing tag rendered). Use for void HTML elements: br, hr, img, input, link, meta, etc.
func (*Element) Render ¶ added in v0.2.3
Render renders the element to the parent. This is a terminal operation.
func (*Element) Set ¶ added in v0.11.0
Set applies multiple attributes or classes at once using KeyValue pairs.
type Event ¶
type Event interface {
// PreventDefault prevents the default action of the event.
PreventDefault()
// StopPropagation stops the event from bubbling up the DOM tree.
StopPropagation()
// TargetValue returns the value of the event's target element.
// Useful for input, textarea, and select elements.
TargetValue() string
// TargetID returns the ID of the event's target element.
TargetID() string
// TargetChecked returns the checked status of the event's target element.
// Useful for checkbox and radio input elements.
TargetChecked() bool
}
Event represents a DOM event.
type Reference ¶ added in v0.2.3
type Reference interface {
// GetAttr retrieves an attribute value.
GetAttr(key string) string
// Value returns the current value of an input/textarea/select.
Value() string
// SetValue sets element.value (inputs, textarea, select).
SetValue(value string)
// SetAttr calls element.setAttribute(key, value).
// Use empty string for boolean attributes (e.g., SetAttr("disabled", "")).
SetAttr(key, value string)
// RemoveAttr calls element.removeAttribute(key).
RemoveAttr(key string)
// SetText sets element.textContent.
// Safe for plain text — does not parse HTML.
SetText(text string)
// Checked returns the current checked state of a checkbox or radio button.
Checked() bool
// On registers a generic event handler (e.g., "click", "change", "input", "keydown").
On(eventType string, handler func(event Event))
// Focus sets focus to the element.
Focus()
}
Reference represents a reference to a DOM node. It provides methods for reading and interaction.
type SignalBool ¶ added in v0.11.0
type SignalBool struct {
// contains filtered or unexported fields
}
SignalBool — same shape for class/attr toggles and Show conditions.
func DeriveBool ¶ added in v0.11.0
func DeriveBool(compute func() bool) *SignalBool
func NewBool ¶ added in v0.11.0
func NewBool(v bool) *SignalBool
func (*SignalBool) Get ¶ added in v0.11.0
func (s *SignalBool) Get() bool
func (*SignalBool) Set ¶ added in v0.11.0
func (s *SignalBool) Set(v bool)
func (*SignalBool) Toggle ¶ added in v0.11.0
func (s *SignalBool) Toggle()
type SignalNodes ¶ added in v0.11.0
type SignalNodes struct {
// contains filtered or unexported fields
}
SignalNodes is an observable list of rendered rows. No generics; the component builds the Elements.
func NewNodes ¶ added in v0.11.0
func NewNodes(v ...*Element) *SignalNodes
func (*SignalNodes) Get ¶ added in v0.11.0
func (s *SignalNodes) Get() []*Element
func (*SignalNodes) Set ¶ added in v0.11.0
func (s *SignalNodes) Set(v []*Element)
type SignalString ¶ added in v0.11.0
type SignalString struct {
// contains filtered or unexported fields
}
SignalString is an observable string cell. UI text/attr/input state lives here. Explicit Get/Set.
func DeriveString ¶ added in v0.11.0
func DeriveString(compute func() string) *SignalString
DeriveString / DeriveBool: read-only computed cells. Re-run automatically when any signal the closure READS changes — no deps argument.
func NewString ¶ added in v0.11.0
func NewString(v string) *SignalString
func (*SignalString) Get ¶ added in v0.11.0
func (s *SignalString) Get() string
func (*SignalString) Set ¶ added in v0.11.0
func (s *SignalString) Set(v string)
func (*SignalString) Update ¶ added in v0.11.0
func (s *SignalString) Update(fn func(string) string)
type ViewRenderer ¶ added in v0.2.0
type ViewRenderer interface {
Render() *Element
}
ViewRenderer returns a Node tree for declarative UI.
Source Files