About HELIX

HELIX Widgets is a declarative widget framework built on top of Unity UI Toolkit. Instead of manipulating VisualElement trees directly, you describe your interface as a tree of Widget objects. HELIX creates the underlying VisualElement tree, reconciles it efficiently on rebuild, and keeps modifiers, theme values, and state in sync automatically.

Where to start

Mental model

HELIX cleanly separates configuration from runtime:

The mental model is intentionally similar to Flutter-style UI:

• Stateless widgets: subclasses of StatelessWidget<T> that rebuild from constructor inputs and context alone.
• Stateful widgets: subclasses of StatefulWidget<T> that own local state and expose a lifecycle (InitState, Build, DidUpdateWidget, and Dispose).
• Keys: preserve mounted element identity when children are reordered or inserted.
• Theme providers: flow values down the tree, resolved at build time through BuildContext.

A complete minimal example

The example below creates a counter label with a button. It covers stateful widgets, SetState, the collection initializer syntax, and modifiers all in one place.

using HELIX.Types;
using HELIX.Widgets;
using HELIX.Widgets.Universal;

// The widget is a lightweight configuration object. Its sole job is to produce a State.
public class CounterLabel : StatefulWidget<CounterLabel> {
  public override State<CounterLabel> CreateState() => new CounterLabelState();
}

// The state owns mutable data and implements Build.
public class CounterLabelState : State<CounterLabel> {
  private int _count;

  public override Widget Build(BuildContext context) {
    return new HColumn(gap: 8, crossAxisAlign: Align.FlexStart) {
      new HText($"Count: {_count}").Heading(context),
      new HButton(onClick: SetState(() => _count++)) {
        new HText("Increment")
      }
    }.Padding(16);
  }
}

Mounting the widget

Every HELIX widget tree is rooted in a WidgetHostElement. Subclass it as a [UxmlElement] so you can drop it into UI Builder or UXML like any other element.

[UxmlElement]
public partial class MyWidgetRoot : WidgetHostElement {
  public MyWidgetRoot() {
    // ToBuildable() wraps the widget in the IBuildable interface the host expects.
    Buildable = new CounterLabel().ToBuildable();
  }
}

Once the element attaches to a panel, HELIX schedules the first build automatically. After that, calls to SetState() trigger reconciled rebuilds where only the parts of the VisualElement tree that actually changed get touched.

Key API reference

The generated C# reference is available under /reference. These are the most useful anchor points when reading the conceptual docs: