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, content). - 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().Child(
html.Span().BindText(c.count).Class("count"),
html.Button().Text("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 (before render) |
Mounted() |
Imperative: DOM operations (measure, focus, scroll) | On every insertion |
Init and Mounted are optional — only add them when there is work 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().Text("Save").BindAttrBool("disabled", saving),
)
Builders take no arguments — children go in Child(...) (variadic) and text in .Text(...).
The only exceptions are A(href), Input(type), Option(value, text) and SelectedOption(value, text).
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, html.Div().Child(...)) // toggle subtree visibility via display:none
html.Ul().BindChildren(c.rows) // keyed list
Lifecycle
Init (once) → Render → Insert → Wire bindings & events → children Mounted → own Mounted
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(attr string) string
- func GetHash() string
- func LocalStorageAvailable() bool
- func LocalStorageClear() error
- func LocalStorageDel(key string) error
- func LocalStorageGet(key string) (string, error)
- func LocalStorageSet(key, value string) error
- func Log(v ...any)
- func OnHashChange(handler func(hash string))
- func OnScrollCapture(handler func(scrollTop float64))
- func Render(parentID string, component Component) error
- func SetDevMode(on bool)
- func SetDocumentAttr(attr, value string)
- func SetHash(hash string)
- func SetLog(log func(v ...any))
- func SupportsLightDark() bool
- 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) BindState(s StateAttr, on *SignalBool) *Element
- func (b *Element) BindStateFunc(s StateAttr, 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) SetState(s StateAttr) *Element
- func (b *Element) String() string
- func (b *Element) Text(text string) *Element
- type Event
- type Reference
- type SignalBool
- type SignalNodes
- type SignalString
- type StateAttr
- 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 reads an attribute from document.documentElement. Returns "" if the attribute is absent.
func LocalStorageAvailable ¶ added in v0.9.0
func LocalStorageAvailable() bool
LocalStorageAvailable reports whether localStorage is accessible in the current browser context. Returns false when blocked by iframe sandbox, privacy settings, or private mode. Used internally by all LocalStorage* functions and available as a public check.
func LocalStorageClear ¶ added in v0.9.0
func LocalStorageClear() error
LocalStorageClear removes all keys. Returns error if storage unavailable.
func LocalStorageDel ¶ added in v0.9.0
LocalStorageDel removes a key. Returns error if storage unavailable.
func LocalStorageGet ¶ added in v0.9.0
LocalStorageGet retrieves a value from window.localStorage. Returns ("", nil) — key absent, storage is functional. Returns ("", error) — storage unavailable.
func LocalStorageSet ¶ added in v0.9.0
LocalStorageSet writes a key-value pair. Returns error if: storage unavailable, value > lsMaxValue, or budget exceeded.
func OnHashChange ¶ added in v0.0.11
func OnHashChange(handler func(hash string))
OnHashChange registers a hash change listener.
func OnScrollCapture ¶ added in v0.13.1
func OnScrollCapture(handler func(scrollTop float64))
OnScrollCapture registra un listener de scroll en FASE DE CAPTURA sobre el documento, de modo que se dispara para CUALQUIER scroller de la página, no solo para la ventana.
Existe porque el evento scroll no burbujea: se dispara únicamente en el elemento que se desplazó. Un shell que quiere reaccionar al scroll de su contenido no puede saber qué descendiente de qué componente es el que realmente desborda, y registrar el listener elemento por elemento lo obligaría a conocer el interior de otros paquetes.
scrollTop es la posición vertical del elemento que disparó el evento. Con varios scrollers en pantalla los valores se intercalan: quien compare posiciones debe tolerarlo con un umbral, no asumir una serie continua.
No hay forma de darlo de baja: es un listener del documento que vive lo que vive la página.
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(attr, value string)
SetDocumentAttr sets an attribute on document.documentElement (<html>). value=="" removes the attribute — consistent with GetDocumentAttr returning "" for absent attributes.
func SupportsLightDark ¶ added in v0.13.3
func SupportsLightDark() bool
SupportsLightDark reports whether the browser can actually RESOLVE the CSS light-dark() color function — not merely parse it.
This is deliberately a BEHAVIORAL probe: it applies "light-dark(rgb(1,2,3), rgb(4,5,6))" to a real, briefly-attached element and reads the resolved backgroundColor back, rather than asking CSS.supports('color', 'light-dark(red, blue)') (the JS equivalent of @supports). Both of those report whether the browser recognizes the SYNTAX; Safari 17.4 is a confirmed case of a browser that recognizes light-dark() but does not correctly resolve it — a syntax-only check would report "supported" on exactly the browser this function exists to catch. See github.com/tinywasm/css's Token.EnhancedVar doc comment for the wider legacy-fallback investigation this came out of; a browser this reports false for is the same population that relies on that fallback, which is why this exists — a component whose only effect is toggling light-dark()-driven color (github.com/tinywasm/components/themetoggle) has nothing to do on such a browser and should not render a control that looks broken when pressed.
color-mix() needs no equivalent probe: every engine shipped it before light-dark() (Safari 16.2 vs 17.5; Chrome 111 vs 123; Firefox 113 vs 120), so a browser this reports true for already has it.
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))
// OnScrollCapture registra un listener de scroll en fase de captura sobre el
// documento: se dispara para cualquier scroller de la página. Ver la función
// de paquete del mismo nombre.
OnScrollCapture(handler func(scrollTop float64))
// 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, content Component) *Element
Show keeps content mounted and toggles its visibility with cond. The subtree is built and attached ONCE — a builder re-run that re-attaches captured elements (the v0.12 panic) is unrepresentable: there is no builder. Hidden means inline display:none on the container, so node identity, listeners and signal bindings survive every toggle, and bindings keep patching while hidden — the subtree is current the moment it reappears.
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) BindState ¶ added in v0.12.1
func (b *Element) BindState(s StateAttr, on *SignalBool) *Element
BindState writes the state's attribute while on is true and removes it when false. This is the ONLY supported way to write a widget state: the value the stylesheet selects on comes from the state itself, so markup and CSS cannot disagree.
Not BindAttrBool: that writes the HTML boolean form (`data-x=""`), which no data-state selector matches. That mistake shipped once and was invisible.
func (*Element) BindStateFunc ¶ added in v0.12.1
BindStateFunc is the computed form, for a state derived from more than one signal.
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.
func (*Element) SetState ¶ added in v0.12.1
SetState writes the state unconditionally, for markup that is born in it.
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()
// ScrollIntoView smooth-scrolls the element into view (e.g. to jump a
// horizontal scroll-snap container to a different panel programmatically —
// the browser resolves the final resting position against any
// scroll-snap-align on this element and its container).
ScrollIntoView()
// ScrollsX reports whether the element can actually scroll along the inline
// axis — its content is wider than its box.
//
// It exists because ScrollIntoView walks EVERY scrollable ancestor, not just
// the one the caller had in mind. A component that drives a horizontal strip
// on narrow screens and lays the same panels out side by side on wide ones
// has to know which it is looking at: on the wide layout the nearest
// scroller is somebody else's, and scrolling it moves the whole application.
ScrollsX() bool
}
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 StateAttr ¶ added in v0.12.1
StateAttr is anything that names a data-state attribute and the value the stylesheet selects on. widget.State satisfies it; nothing else needs to.
Declared here rather than imported so that dom keeps no dependency on the widget vocabulary — the same seam Class.AsAttr already uses in the other direction.
type ViewRenderer ¶ added in v0.2.0
type ViewRenderer interface {
Render() *Element
}
ViewRenderer returns a Node tree for declarative UI.
Source Files