Annotations

Mateu’s declarative UI is driven by Java annotations placed on classes, fields, and methods. The table below lists every annotation by category.

Routing and registration

Annotation	Target	Description
`@UI`	Class	Registers a class as a Mateu UI entry point
`@Route`	Class	Maps a class to a URL path
`@HomeRoute`	—	Declares the default home path
`@BaseRoute`	—	Sets a base path prefix
`@UISpec`	Class	Uses a YAML file as the component tree instead of `ComponentTreeSupplier`

App structure

Annotation	Target	Description
`@App`	Class	Applies an app layout variant; optional `themeToggle` adds dark/light mode switch
`@DrawerClosed`	Class	Starts the drawer/sidebar in closed state
`@Logo`	Class	Sets the app logo URL
`@FavIcon`	Class	Sets the browser favicon
`@KeycloakSecured`	Class	Protects a page with Keycloak authentication
`@AI`	Class	Enables AI/SSE integration

HTML head injection

These annotations inject tags into the <head> of the generated HTML page at compile time. All three are repeatable and can be combined on the same @UI class.

Annotation	Target	Description
`@Script`	Class	Injects a `<script>` tag (supports `type`, `defer`, `async`, `crossorigin`)
`@Link`	Class	Injects a `<link>` tag (stylesheets, preloads, fonts…)
`@Meta`	Class	Injects a `<meta>` tag (`name`, `http-equiv`, `charset`)

Page metadata

Annotation	Target	Description
`@Title`	Class	Sets the page title
`@PageTitle`	Class	Sets the browser tab title
`@Subtitle`	Class	Sets the page subtitle
`@Label`	Field, method	Overrides the display label for a field
`@Help`	Class, field, method	Adds a help text / tooltip

Styling

Annotation	Target	Description
`@Style`	Class, field	Inline CSS applied to the element
`@CssClasses`	Class, field	CSS class names applied to the element
`@DivStyle`	Class, field	Inline CSS applied to the wrapping div

Layout

Annotation	Target	Description
`@FormLayout`	Class	Renders a multi-column form layout
`@HorizontalLayout`	Class	Renders children in a horizontal row
`@VerticalLayout`	Class	Renders children in a vertical column
`@SplitLayout`	Class	Renders a resizable split panel
`@Scroller`	Class	Wraps content in a scrollable container
`@FoldedLayout`	Class	Renders each `@Section` as a collapsible panel
`@Compact`	Class	High-density mode — tighter spacing and smaller controls
`@Zones` / `@Zone`	Class	Declares side-by-side column zones for sections
`@Inline`	Field	Expands a nested type’s fields into the parent section inline
`@DetailFormCustomisation`	Field	Controls position and columns of an embedded detail form
`@MasterDetail`	Field	Renders a field as a master-detail panel

Grouping and sections

Annotation	Target	Description
`@Section`	Field, method	Groups following fields under a heading
`@Tabs`	Class	Wraps page content in a tabbed container
`@Tab`	Field, method	Assigns a field to a named tab
`@Accordion`	Class	Wraps content in an accordion
`@AccordionPanel`	Field, method	Assigns a field to an accordion panel
`@List`	Field	Renders a list (ordered or unordered)
`@H1` – `@H5`	Field	Renders the field value as a heading

Actions and buttons

Annotation	Target	Description
`@Button`	Field, method	Renders a button that calls the annotated method
`@Action`	Class, method	Attaches a configurable action
`@RowAction`	Method	Marks a method as a row-level action in a grid
`@ListToolbarButton`	Method	Adds a toolbar button to a listing
`@ViewToolbarButton`	Method	Adds a toolbar button to a view
`@Toolbar`	Field, method	Places an element in the toolbar area
`@WizardCompletionAction`	Field, method	Marks the final action of a wizard
`@Banner`	Method	Renders a highlighted message block below the page header
`@Fab`	Method	Renders a Floating Action Button fixed to the bottom-right

Annotation	Target	Description
`@Menu`	Field	Marks a field as a navigation menu entry
`@Breadcrumb`	—	Defines a single breadcrumb item
`@Breadcrumbs`	Class	Adds a breadcrumb trail to a page
`@Header`	Field	Places a field in the page header slot
`@Footer`	Field	Places a field in the page footer slot

Field visibility and access

Annotation	Target	Description
`@Hidden`	Class, field	Hides the field
`@HiddenInCreate`	Field	Hides the field only in create mode
`@HiddenInEditor`	Field	Hides the field only in editor mode
`@HiddenInList`	Field	Hides the field only in list view
`@HiddenInView`	Field	Hides the field only in view mode
`@ReadOnly`	Class, field	Makes the field non-editable
`@Disabled`	Class, field, method	Disables the field or button
`@EyesOnly`	Class, field, method	Restricts visibility to specific roles/groups
`@EditableOnlyWhenCreating`	Field	Allows editing only during record creation

Validation

Annotation	Target	Description
`@Validation`	Class	Adds a cross-field validation condition
`@Rule`	Class	Adds a conditional UI rule (show/hide, enable/disable)

Triggers and events

Annotation	Target	Description
`@Trigger`	Class	Fires an action on a lifecycle event

Field types and rendering

Annotation	Target	Description
`@Lookup`	Field	Renders a lookup / search field
`@Option`	—	Declares an option for an enum or select field
`@OptionsLayout`	Field	Controls how options are laid out
`@UseRadioButtons`	Field	Renders enum options as radio buttons
`@Representation`	Field	Sets a non-default field stereotype
`@Stereotype`	Field	Alias for `@Representation`
`@Filterable`	Field	Marks a field as filterable in a listing
`@Colspan`	Field	Sets how many columns a field spans
`@ColumnWidth`	Field	Sets the column width in a grid

Display and status

Annotation	Target	Description
`@KPI`	Field	Renders a field as a KPI tile
`@Status`	Field	Maps field values to coloured status badges
`@MappedValue`	Field	Maps raw values to display strings
`@SliderMin` / `@SliderMax`	Field	Sets the min/max range for a slider field
`@Details`	Field	Renders a field inside a collapsible details panel
`@Widget`	Field	Renders a field as a widget
`@PlainText`	Field	Renders the field value as plain read-only text (no input chrome)
`@Badge`	Field	Renders a boolean field as an inline coloured chip in the form body
`@BadgeInHeader`	Field	Renders a field as a status chip in the page header strip
`@Multiline`	Field	Allows a `@PlainText` field to wrap instead of truncate

Data and persistence

Annotation	Target	Description
`@MasterDetail`	Field	Embeds a master-detail grid for a related collection
`@Composition`	Field	Links to a composed entity via a CRUD repository
`@Subresource`	Field	Marks a field as a sub-resource
`@PrimaryKey`	Field	Marks the primary key field
`@GeneratedValue`	Field	Generates a field value via a `ValueGenerator`

Composing annotations

Any of the annotations above (except the routing ones) can be bundled into a single semantic annotation of your own — e.g. @ProveedorId instead of a full @Lookup, or @ImporteTotal instead of @Stereotype(money) @Label(…) @Help(…). See Semantic (Composed) Annotations.