Form

What it does

The root window. Give your app somewhere to live.

Each project can contain multiple forms. Add a form with Ctrl+N; create a separate project with Ctrl+Shift+N.

Set it up

1. Select your form in the designer or Solution Explorer.
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.

Add a Label named welcomeLabel. Form startup callbacks run after all component scripts are installed. main.js is separate from the form’s own script.js.

forma.on("Load", () => {
  forma.set("welcomeLabel", "text", "Let’s build something.");
});

Component properties

This component uses the shared inspector fields below; it has no additional component-specific inspector fields.

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.

Only applicable browser events fire: a control without text input will not produce native input events just because a handler is registered. 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.Form
{
    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