Display Annotations

These annotations control how field values are presented visually — as tiles, collapsible panels, navigation entries, or custom widgets.

---

@Avatar

Target: FIELD

No attributes. Renders the field as an avatar component — either an image (when the field holds a URL) or a styled initials badge (when the field holds a name string).

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Avatar {}

Example

public class UserCard {
    @Avatar
    String profilePhotoUrl;

    String displayName;
}

---

@KPI

Target: FIELD

No attributes. Renders the field as a Key Performance Indicator tile — a large numeric metric with a label, intended for dashboard pages.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface KPI {}

Example

public class DashboardPage {
    @KPI
    int totalInvoices = 142;

    @KPI
    String totalRevenue = "€ 48,320";

    @KPI
    double averageOrderValue = 340.28;
}

---

@Widget

Target: FIELD

No attributes. Marks a field as a custom widget. The field’s type must implement the appropriate widget interface. Mateu delegates rendering entirely to the widget.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Widget {}

Example

public class DashboardPage {
    @Widget
    Component salesChart;

    @Widget
    Component revenueKpi;
}

---

@Details

Target: FIELD

Wraps the field content in a collapsible details/summary component. The summary attribute is the header shown in the collapsed state; set opened to true to start the panel expanded.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Details {
    String theme() default "";
    String style() default "";
    String summary() default "";
    boolean opened() default false;
}

Attributes

Attribute	Type	Default	Description
summary	String	""	Label shown in the collapsed header
opened	boolean	false	Whether the panel is initially expanded
theme	String	""	Visual theme variant
style	String	""	Inline CSS applied to the details container

Example

public class OrderForm {
    String orderId;
    String status;

    @Details(summary = "Internal notes", opened = false)
    String internalNotes;
}

---

@Menu

Target: FIELD

Renders the field as a navigation menu entry. The description attribute is a hint for AI assistants to understand the purpose of the menu item.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Menu {
    boolean selected() default false;
    String description() default "";
}

Attributes

Attribute	Type	Default	Description
selected	boolean	false	Whether this menu entry is shown as active/selected
description	String	""	Hint text for AI assistants describing the entry’s purpose

Example

public class SidebarPage {
    @Menu(selected = true, description = "Main overview dashboard")
    Component dashboard;

    @Menu(description = "Manage customer records")
    Component customers;
}

---

@Button

Target: FIELD, METHOD

No attributes. Renders a method as a clickable button, or a field as a button action. When placed on a method, Mateu calls that method on click. See also the actions reference.

public @interface Button {}

Example

public class OrderForm {
    String orderId;

    @Button
    void save() {
        // called when the button is clicked
    }
}

---

@State

Target: FIELD

Marks a field as part of the tracked component state. State fields can be referenced in @Rule conditions and @Trigger expressions without triggering a full server round-trip.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface State {
    String value();
}

Attributes

Attribute	Type	Description
value	String	State identifier used in rule and trigger expressions

Example

public class WizardForm {
    @State("currentStep")
    int step = 1;

    String firstName;
    String lastName;
}

---

@Stereotype vs @Representation

These two annotations are closely related but govern different rendering contexts:

Annotation	Controls
@Stereotype	The input widget used in edit mode
@Representation	How the value is displayed in read-only / list view

Both can be combined on the same field to independently control each context.

// Edit mode: textarea input; read-only mode: rendered as Markdown
@Stereotype(FieldStereotype.textarea)
@Representation(FieldStereotype.markdown)
String description;

See field-types for the complete FieldStereotype enum reference.