Widgets

Widgets are composable UI elements. From buttons in a sidebar to property grids in a tool panel, widgets are the primary way users interact with plugin logic.

Building with `egui`

The platform uses egui, an immediate-mode GUI library. The UI is described every frame as a function of the current state. This is similar to declarative frameworks like React: instead of manually updating elements, the UI is described based on current data.

fn my_custom_widget(ui: &mut Ui, state: &mut MyWidgetState) {
    ui.heading("Custom Workspace");
    
    // UI elements react immediately to user interaction
    if ui.button("Process Data").clicked() {
        state.is_processing = true;
    }
    
    if state.is_processing {
        ui.spinner();
    }
}

Form-First Design

While custom UI can be built using raw egui code, we recommend a Form-First approach for most tools. Instead of writing manual layout code, you define a Rust struct that represents tool properties. The SDK then renders a consistent interface.

Benefits of this approach:

Consistency: Tools match the look and feel of the rest of the application.
Simplicity: Focus is on the data the tool needs, rather than layout.
Automatic Binding: Changes in the UI are sent to the tool’s asynchronous run method as property updates.

Form Property Types (`ToolProp`)

When defining a form, you choose from a library of built-in property types:

Prop Type	Use Case
Heading	Organizing forms into sections.
F64	Numeric inputs like height, width, or tolerance (includes slider support).
String	Text inputs for names, descriptions, or search queries.
Button	Triggering one-off actions within a tool.
DropDown	Selecting from a list of modes or options.
ColorPicker	Choosing RGB/RGBA values.
FileSelect	Opening local files for import or export.
Node	Selecting a node from the scene hierarchy.
Representation	Picking a geometric representation to modify.

Visual Language and Icons

The system uses the Phosphor Icons library. Icons are available throughout the SDK and can be used in tabs, buttons, and headers by prefixing the icon name with ph- (e.g., ph-cube or ph-star).

You can also load custom images or SVG assets to use in widgets for further customization.

Design Guidelines

To ensure a native feel within the ecosystem:

Group Related Fields: Use Heading properties to break up complex forms.
Provide Sensible Defaults: Initialize ToolProperties with values suitable for the most common use case.
Use Viewport Overlays for Spatial Tasks: For tasks involving interaction in 3D space, use a Viewport Overlay to provide instructions or context-sensitive widgets near the cursor.

Bevy Plugins Objects