Widget Catalog

This page groups the full public widget surface by purpose. For constructor signatures and parameter details, see the generated API reference under /reference. This page focuses on what each widget is for and how they fit together.

Base types for custom widgets

Widget is the root base class. Application-level widgets should inherit from one of these specializations:

Use WidgetHostElement to insert any widget tree into ordinary Unity UI Toolkit. It serves as the integration boundary between the two worlds.

Layout

Axes and flow

HColumn and HRow are the two most common layout widgets. They lay children out vertically and horizontally respectively, and both support mainAxisAlign, crossAxisAlign, gap, and reverse:

new HColumn(gap: 16, crossAxisAlign: Align.Stretch) {
  new HText("Account settings"),
  new HRow(gap: 8) {
    new HButton(child: new HText("Cancel")),
    new HButton(HButtonVariant.Flat, child: new HText("Save"))
  }
}

Use HFlex when the axis must be dynamic or when flex wrap is needed. Use HStack when children should overlap with absolute positioning while still allowing non-positioned children to flow normally.

Supporting layout widgets

Text and icons

HText

HText wraps a UI Toolkit Label and adds text-specific options: rich text, selectable text, language direction, and explicit TextStyle values.

Apply theme-aware typography with extension methods:

new HText("Section heading").Heading(context);
new HText("Body copy paragraph.").Body(context);
new HText("Small metadata label").Caption(context);
new HText("Hero display text").Display(context);

Each helper resolves the correct TextStyle from the active PrimitiveTheme, so the size, weight, and color update automatically when the theme changes.

HIcon

HIcon is a Label specialized for font-based icon sets. Pass a Unicode glyph constant and a font definition:

new HIcon(FaSolidIcons.MagnifyingGlass, FaSolidIcons.FontDefinition);
new HIcon(FaSolidIcons.FloppyDisk,      FaSolidIcons.FontDefinition);

The bundled Font Awesome solid icon constants are available through FaSolidIcons.

Buttons

HButton is a themed, stateful button that handles hover, press, focus, and disabled states automatically.

new HButton(
  HButtonVariant.Soft,
  onClick: Save,
  child: new HRow(gap: 8) {
    new HIcon(FaSolidIcons.FloppyDisk, FaSolidIcons.FontDefinition),
    new HText("Save")
  }
);

Control the appearance with:

• Variant: HButtonVariant. Supported values are: Flat, FlatTwoState, Soft, SoftTwoState, Outline, Ghost, and TwoState.
• Size: HButtonSize, which controls padding and minimum height.
• Radius: HInputRadius, which controls corner rounding.

For external control, pass a ButtonController. Without one, the button creates and manages one internally.

Text fields

HTextField is the themed text-input widget.

Uncontrolled: provide an initial value and react to change or submit callbacks:

new HTextField(
  initialValue: playerName,
  onChanged: value => playerName = value,
  onSubmitted: SubmitName
);

Controlled: bind a TextEditingController to read or set the value programmatically.

Sliders

HSlider supports two modes:

Value slider: controlled via a SliderController or initial-value callbacks:

new HSlider(
  axis: Axis.Horizontal,
  initialValue: volume,
  onChanged: value => volume = value
);

Scrollbar: bind a ScrollController. HELIX will configure the range and thumb size automatically:

new HSlider(_scroll)

When created from a scroll controller, the slider uses the scrollbar theme by default.

Scrolling and virtualization

HScrollView

HScrollView creates a scrollable container. Use it for forms, settings panels, and small-to-medium dynamic content where all children can be mounted at once:

new HScrollView(Axis.Vertical) {
  new HColumn(gap: 8) {
    rows.Select(row => new HText(row.Title)).Spread()
  }
}.Fill();

HListView (virtualized)

HListView is the correct choice for long lists. It builds row widgets on demand as the visible range changes, keeping the VisualElement count small regardless of how many items there are:

new HListView(
  (context, index) => new HBox {
    new HText($"Item {index + 1}")
  }.Padding(12),
  count: 1000,
  fixedItemHeight: 48f
);

Set fixedItemHeight when all rows are the same height to allow O(1) scroll position calculations. For variable-height content, use dynamic height mode, which performs extra measurement work in exchange for flexibility.

HPanView

HPanView supports free two-dimensional panning of a larger child surface. It is well-suited for map-like views, node editors, canvas tools, and any content that is not naturally linear.

Navigation

HNavStack hosts a stack of pages and handles push, pop, and replacement with optional transitions. Reach the mounted element through a GlobalKey<T> stored as a state field:

private readonly GlobalKey<NavStackElement> _nav = new();

new HNavStack(key: _nav).Fill();

_nav.Element.PushReplacement(new WidgetNavPage {
  Buildable = new SettingsPage().ToBuildable()
});

Built-in transitions include InstantPageTransition, FadePageTransition, and SlidePageTransition. Implement PageTransition to create custom ones.

HScaffold is a higher-level page shell that manages named layout areas such as a body slot, navigation surfaces, and common chrome. Use it when pages share structural chrome that should not be rebuilt on each navigation.

Prompts and input glyphs

HPrompt displays context-sensitive glyphs for input bindings. Rendering is provider-based, meaning the same prompt widget automatically shows the correct glyph for keyboard/mouse, Xbox, PlayStation, Nintendo Switch 2, Steam Deck, or Steam Controller, depending on the active device.

Key types:

Prompt widgets are useful for action bars, tutorial hints, rebinding screens, and context-sensitive control help.

Visual and painting helpers

The HELIX.Widgets.Visual namespace contains lower-level drawing helpers for custom UI visuals: