Getting Started

ELEMENTS can be easily added to almost any Unity project, so long as you are using Unity 6 or above. Backwards compatibility is planned, but a low priority at this time.

Installation

Install R3

ELEMENTS depends on R3. Install it from NuGet using NuGetForUnity — search for "R3" and install the latest stable version.

Install ELEMENTS

Add ELEMENTS via the Unity Package Manager using the following git URL:

https://github.com/1by3/ELEMENTS.git?path=Assets/ELEMENTS

You can pin a specific version by appending a tag:

https://github.com/1by3/ELEMENTS.git?path=Assets/ELEMENTS#1.0.0

Your first Component

In ELEMENTS, your UI is made up of a series of "Components". A Component is a single class that contains both your state and your UI definition.

Building a Component

Start by making a class that inherits from Component. Override the Render method to return the element tree that defines your UI...

public class ExampleComponent : Component
{
    protected override IElement Render()
    {
        return new VerticalGroup(
            new Label("The button has been clicked 0 times."),
            new Button(new Label("Click Me!"))
        );
    }
}

We'll talk more about the elements used (VerticalGroup, Label, and Button) shortly. For now, let's talk about how we can make this static UI interactive with state.

Adding State

State lives directly on your Component as fields. Use ReactiveProperty to make state that automatically updates the UI when it changes...

public class ExampleComponent : Component
{
    public readonly ReactiveProperty<int> Count = new(0);

    public void Increment()
    {
        Count.Value += 1;
    }

    protected override IElement Render()
    {
        return new VerticalGroup(
            new Label()
                .BindText(Count.Select(count => $"The button has been clicked {count} times.")),
            new Button(new Label("Click Me!"))
                .OnClick(_ => Increment())
        );
    }
}

We've done a couple of things here. First, we've bound the Text property of our Label to a transformed version of the Count property. This will make the text of the label update each time Count is changed. We've also mapped the Increment method to be called when the Button is clicked.

You now have a dynamic and interactive UI built with ELEMENTS!

Rendering your UI

The simplest way to render your UI is from a MonoBehaviour using the RenderComponent extension method on a UIDocument...

public class GameUI : MonoBehaviour
{
    [SerializeField] private UIDocument uiDocument;

    private void OnEnable()
    {
        uiDocument.AddStyleSheet("ELEMENTS/DefaultStyles");
        uiDocument.RenderComponent<ExampleComponent>();
    }
}

A couple of notes...

• We loaded the default ELEMENTS stylesheet onto the UIDocument using the AddStyleSheet helper. This is optional, but highly recommended for a good starting point with styles. For more on styling, including Tailwind-style utility classes, see Utility Classes.
• We used the OnEnable method. This is an important detail that allows your UI to update when Unity reloads your game if you make code changes. If your UI is disappearing on reload, this might be why.

If you start your game, you should see your UI on the screen!

Setting up an ElementPortal

If your UI uses floating elements like Dialog, Popover, Alert, or ContextMenu, you need an ElementPortal in your scene. The portal creates an overlay surface that these elements render into.

Add the ElementPortal component to a GameObject in your scene. It requires a UIDocument on the same GameObject — one will be added automatically.

When an ElementPortal is enabled, it becomes available as ElementPortal.Current. Floating elements like Dialog and Popover use this automatically, so you don't need to pass the portal reference manually.