Using Guigui

Guigui is an immediate-mode-inspired GUI framework for Go on top of Ebitengine. "Inspired" is the key word: widgets are retained Go structs that you own and keep across ticks, but their child tree and presentation are reconstructed by re-running Build whenever relevant state changes — the way Compose or SwiftUI re-run a view function. You hold the state in struct fields; the framework decides when to rebuild, lay out, and redraw.

Read this whole file before writing widget code; the lifecycle rules below are the part people get wrong.

Freshness. Verified against Guigui at commit 4ebb3fc7 (2026-06-25). Guigui is alpha and its API may change — if anything here disagrees with the source, the source wins: trust *.go in the module root and the programs under example/ over this file, and update this skill when you find drift.

The mental model

• A widget is a struct that embeds guigui.DefaultWidget and overrides the methods it needs. DefaultWidget supplies no-op defaults for every method, so override only what matters.
• A widget must work from its zero value — declare children as plain (non-pointer) fields and reference them as &w.child. Do not allocate them in a constructor; var w Foo must already be usable.
• The framework runs two decoupled cycles. Each tick (Ebitengine's Update, at the app's TPS — 60×/sec by default, or whatever TPS is configured) settles the tree: it may run Build (reconstruct the child tree), Layout (position the children), and the Handle*Input methods an indeterminate number of times, interleaved, until state stops changing — then calls Tick exactly once. Rely only on these guarantees: within a pass Build precedes Layout, and Tick runs once, last. Do not assume a fixed count of Build, Layout, or input passes per tick, nor that an input handler runs only once before Tick. Each frame (Ebitengine's Draw, at the display's refresh rate) does Draw. Ticks and frames are not one-to-one — there may be more or fewer frames than ticks — so put per-step logic in Tick, never in Draw.
• You never invoke a widget's framework-driven methods (Build, Layout, Tick, Draw, the Handle*Input methods, Env, …) yourself — you set fields and register handlers, and the framework calls back. The one exception is Measure: a parent or composite widget calls a child's Measure directly to size it (it is what LinearLayout and the shared layout() helper do).

Minimal application

package main

import (
	"image"
	"log"

	"github.com/guigui-gui/guigui"
	"github.com/guigui-gui/guigui/basicwidget"
)

type Root struct {
	guigui.DefaultWidget

	background basicwidget.Background
	hello      basicwidget.Text
}

func (r *Root) Build(context *guigui.Context, adder *guigui.ChildAdder) error {
	adder.AddWidget(&r.background)
	adder.AddWidget(&r.hello)

	r.hello.SetValue("Hello, Guigui")
	return nil
}

func (r *Root) Layout(context *guigui.Context, widgetBounds *guigui.WidgetBounds, layouter *guigui.ChildLayouter) {
	layouter.LayoutWidget(&r.background, widgetBounds.Bounds())
	layouter.LayoutWidget(&r.hello, widgetBounds.Bounds())
}

func main() {
	if err := guigui.Run(&Root{}, &guigui.RunOptions{
		Title:         "Example",
		WindowMinSize: image.Pt(480, 320),
	}); err != nil {
		log.Fatal(err)
	}
}

guigui.Run(root, *RunOptions) starts the app. RunOptions carries Title, WindowSize / WindowMinSize / WindowMaxSize, AppScale, and an optional RunGameOptions passed through to Ebitengine.

The Widget interface

Embed guigui.DefaultWidget, then override as needed:

…