Getting Started

HELIX Widgets is designed to live inside Unity UI Toolkit. The main integration boundary is WidgetHostElement, which you can place in UXML, subclass as a custom UXML element, or create from C# and attach to an existing VisualElement tree.

Packages

Both packages target Unity 6000.4 or later.

Installing from Git

Add the packages through Window → Package Manager → + → Add package from Git URL:

# Core
https://github.com/helightdev/HELIX.git?path=src/HELIX/Assets/Plugins/HELIX

# Widgets
https://github.com/helightdev/HELIX.git?path=src/HELIX/Assets/Plugins/HELIX.Widgets

Installing from the repository

If you are working directly inside this repository, the packages live at:

src/HELIX/Assets/Plugins/HELIX
src/HELIX/Assets/Plugins/HELIX.Widgets

Common namespaces

Add these using directives to any file that works with HELIX Widgets:

using HELIX.Types;                        // Colors, Axis, Align, Border, and other primitives
using HELIX.Widgets;                      // Widget, StatelessWidget, StatefulWidget, BuildContext
using HELIX.Widgets.Modifiers;            // Modifier types and fluent extension helpers
using HELIX.Widgets.Universal;            // HColumn, HRow, HText, HButton, HTextField, HSlider...
using HELIX.Widgets.Universal.Styles;     // HButtonVariant, HButtonSize, HInputRadius
using HELIX.Widgets.Universal.Theme;      // PrimitiveTheme, PrimitiveBaseTheme

Hosting a widget tree

The preferred integration point is WidgetHostElement. Subclass it and mark it with [UxmlElement] to make it available in UI Builder and UXML:

using HELIX.Widgets;
using HELIX.Widgets.Universal;
using UnityEngine.UIElements;

[UxmlElement] 
public partial class InventoryPanel : WidgetHostElement {
  public InventoryPanel() {
    Buildable = new HColumn(gap: 8) {
      new HText("Inventory"),
      new HButton(child: new HText("Sort"))
    }.ToBuildable();
  }
}

You can also create a WidgetHostElement from C# and add it to any existing VisualElement:

var host = new WidgetHostElement {
  Buildable = new InventoryList().ToBuildable()
};
rootVisualElement.Add(host);

Once the element attaches to a panel, HELIX schedules the first build and constructs the widget subtree. After that it reconciles on SetState calls or theme changes, only touching the parts of the VisualElement tree that actually changed.

Building with collection initializers

Container widgets implement Add, so HELIX code reads naturally with C# collection initializers:

return new HRow(gap: 12) {
  new HText("Health"),
  new HBox(background: MaterialColors.Red).Expand(),
  new HText("82")
};

Single-child widgets also support initializer syntax. The first item added becomes the child:

new HButton(onClick: Save) {
  new HText("Save")
}

Conditional and projected children

Use WidgetListExtensions helpers to keep the list readable even with conditional or dynamically projected items:

new HColumn {
  new HText("Profile"),
  new HText("Admin").If(user.IsAdmin),      // included only when the predicate is true
  actions
    .Select(a => new HButton(child: new HText(a.Label)))
    .Spread(new HGap(8))                    // flattens a sequence into the parent list
};

Applying modifiers

Modifiers are the normal way to size, space, clip, or decorate a widget after constructing it. The fluent methods chain onto any widget and return the same widget for further chaining:

new HBox(background: MaterialColors.Blue) {
  new HText("Selected")
}.Padding(12).Margin(8).Clip().Expand();

You can also pass an explicit modifiers array through the constructor when that reads better:

new HColumn(
  modifiers: new ModifierSet { 
    PaddingModifier.Of(16),
    MarginModifier.Only(top: 8),
    ClipModifier.Clip
  }
) {
  new HText("Settings")
};

Reading theme values

Every Build call receives a BuildContext that resolves theme tokens and auto-subscribes to theme changes:

public override Widget Build(BuildContext context) {
  var surface = context.GetThemed(PrimitiveTheme.Surface);

  return new HBox(background: surface) {
    new HText("Theme aware").Body(context)
  }.Padding(16);
}

HText extension methods like Heading, Body, Caption, and Display are shorthand for resolving typography from the active primitive theme and applying it to a label.

For more on providers, token overrides, and the substance system, see Theming & Modifiers.