LoadingOverlay

What it does

A tray service that covers its target while work runs.

This is a component tray service. It appears below the form and does not take a canvas rectangle.

Set it up

1. Add LoadingOverlay from Toolbox.
2. Set its Name to sample for the examples below. Names are case-sensitive.
3. Configure the component-specific properties below.
4. Open the Events inspector to add a handler: methods go in event.js, imports and subscriptions in script.js. Right-click View Events or View Script to edit either file. Use View CSS for scoped styles and View Custom Properties for JSON values.
5. Save sources, save the project, and open a fresh Preview. Scripts execute in Preview.

JavaScript example

These examples use supported inline subscriptions for brevity. The Events inspector can generate separate class methods in event.js instead.

Put this on a Button. The overlay lives in the tray; choose its visual target with targetId. A finally block stops loading even when work fails.

forma.on("Click", async () => {
  forma.set("sample", "isActive", true);
  try {
    await new Promise(resolve => setTimeout(resolve, 1000));
  } finally {
    forma.set("sample", "isActive", false);
  }
});

Component properties

Runtime property API

Use forma.get("sample", key), forma.set("sample", key, value), or forma.bind("sample", key). Read a binding with .value; write only when the Binding column permits it. Numbers and booleans must keep their types. Arrays are passed directly, not as JSON strings.

Set commands cross the native bridge asynchronously. An immediate get after set may return the previous value. Observe a binding or use the assigned value locally. Getter arrays are copies. Geometry is configured model geometry; layout and CSS may override rendered bounds.

Shared inspector fields

Events and lifecycle

Component hooks: Relevant DOM events and shared lifecycle events.

Tray services have lifecycle events even without a visible control. Event names are case-insensitive. Put handlers on the component producing the event; a Timer Tick handler belongs to the Timer, or can be observed through forma.root.on("Tick", handler). See the event guide for payloads, validation, cleanup, and startup order.

Property-change payload

All components can report PropertyChanged for changed projected runtime properties. Handlers expose source/subscriber component handles; native DOM targets remain available. Input/Change can supply typed property values, while Click normally supplies identity without a property/value pair.

forma.on("PropertyChanged", ({ source, property, value, previousValue, origin }) => {
  console.log(source.name, property, previousValue, "→", value, origin);
});

Use forma.root.on(...) to observe the active form, and event.toJSON() for portable logs. Subscriptions return unsubscribe and are cleaned up with the subscribing script.

C# example

Use this in a configured Forma C# host, not in script.js. The renderer is your host's WebView2Renderer instance.

var sample = new Forma.Core.Controls.LoadingOverlay
{
    Name = "sample"
};
await renderer.RenderAsync(sample);

C# model reference

These are Core constructor defaults, not necessarily the Builder’s drop-time styles or size. Appearance fields belong to Builder Appearance. C# events are not all forwarded to JavaScript.

Core methods: GetRenderState(), HandleRuntimeEvent(runtimeEvent), Add(child), Insert(index, child), MoveChild(child, index), Remove(child).

Core events: ChildAdded, ChildRemoved, PropertyChanged.

Related guides

• Runtime properties
• Scripts, styles & custom JSON
• main.js, imports & providers
• Implementation status