Hlive Core

HLive Core

HLive is a server-side virtual-DOM framework for Go — think Phoenix LiveView for Go. You build the UI as a tree of Go values; HLive renders the initial HTML, then keeps a WebSocket open and pushes DOM diffs whenever your state changes. All logic (DB, business rules, API calls) stays in Go — you write no JavaScript.

The conventional import alias is l:

import l "github.com/SamHennessy/hlive"

Builders

For everyday page markup, prefer the hhtml builders (Div(...), Button(...), Class("...")) — they're typed and autocompleting. See the hlive-hhtml skill. The functions below are the underlying primitives that hhtml wraps; use them directly for dynamic tag names, or when you haven't imported hhtml.

With hhtml you rarely choose T vs C by hand — a builder like Button(...) becomes a Component automatically when it contains an event binding. With the raw primitives, pick T until the element needs to respond to a browser event, then C; reach for CM only when you need Mount/Unmount.

Events

There are exactly two event-binding constructors: l.On and l.OnOnce. There are no per-event helpers like OnClick/OnKeyUp — pass the DOM event name as a string.

Button(
    l.On("click", func(ctx context.Context, e l.Event) {
        // handlers ARE where you fetch from a DB / API — they run on the server
    }),
    "Save",
)

Input(
    Type("text"),
    l.On("keyup", func(ctx context.Context, e l.Event) {
        message = e.Value
    }),
)

(Button/Input/Type are hhtml builders; the binding makes them Components automatically. The equivalent with raw primitives is l.C("button", l.On(...)).)

l.OnOnce("focus", ...) binds a handler that fires once then removes itself.

The l.Event struct carries (only the fields relevant to the event type are set):

• Value string / Values []string — input value(s)
• Selected bool — checkbox/radio checked, or select option selected
• Key, CharCode, KeyCode, ShiftKey, AltKey, CtrlKey — keyboard events
• File *l.File — file inputs/uploads
• IsInitial bool — true when a browser re-sent pre-filled field data after a page reload (see Initial sync below)

Reactive state with Box

l.Box(v) wraps a value in a thread-safe container that is also a renderable node — drop it into the tree and it renders its current value. Read/write it safely with Get, Set, and Lock:

count := l.Box(0)

Button(
    l.On("click", func(_ context.Context, _ l.Event) {
        count.Lock(func(v int) int { return v + 1 }) // read+write under one lock
    }),
    count, // renders the current value
)

For a plain variable you can also pass it by reference so renders pick up the latest value: P("Hello, ", &message). Box is preferred when more than one goroutine (e.g. PubSub) can touch the value.

Attributes and styling

l.Attrs{"type": "text", "placeholder": "name"}          // plain attributes
l.Class("btn btn-primary")                              // ordered class list
l.ClassBool{"active": isActive, "disabled": !ok}        // toggle classes on/off
l.ClassList{"a", "b", "c"}                              // add a slice of classes
l.Style{"color": "red", "display": nil}                 // nil removes a rule

Ordering note: within a single ClassBool/Style the order is not preserved; add separate elements when order matters. Re-adding the same class key updates the existing one.

With hhtml, set plain attributes with the typed funcs (Type("text"), Placeholder("name"), Class("btn")) instead of l.Attrs; keep the core l.ClassBool/l.ClassList/l.ClassOff/l.Style types for toggling classes and styles on/off.

Page and server

import (
    l "github.com/SamHennessy/hlive"
    . "github.com/SamHennessy/hlive/hhtml"
)

func home() *l.Page {
    page := l.NewPage()
    page.DOM().Title().Add("My App")
    page.DOM().Head().Add(Link(Rel("stylesheet"), Href("/assets/main.css")))
    page.DOM().Body().Add( /* your tree, built with hhtml */ )
    return page
}

func main() {
    http.Handle("/", l.NewPageServer(home)) // PageServer is an http.Handler
    http.ListenAndServe(":3000", nil)
}

page.DOM() is a method that returns the document; .Title(), .Head(), .Body(), and .HTML() are methods on it. (Some older README snippets show page.DOM.Body as a field — that's stale; always call page.DOM().Body().)