One element, a whole app: Mateu inside Oracle Visual Builder
Replace your Visual Builder app's root page with a single component and a complete business app runs inside it — header, menu, listings, record pages, forms, validation — drawn with your app's own Redwood. No frontend co
Replace your Visual Builder app's root page with a single component and a complete business app runs inside it — header, menu, listings, record pages, forms, validation — drawn with your app's own Redwood. No frontend code, no iframe.
If you build apps in Oracle Visual Builder Studio, you know the trade-off. The page designer is excellent for laying out a page, and every non-trivial business screen still means variables, action chains, service connections and a fair amount of wiring. Multiply that by the forty screens of a back office and the wiring becomes the project.
Mateu takes the other route. It is a model-driven UI system: you declare what a screen is — a record, its fields and rules, the actions on it — and Mateu renders it. The declaration can be code (Java, C# or Python) or data (YAML). A listing with search, sorting and filters, record pages, create and edit forms, validation in the browser and again on the server: all of it comes from the declaration. No frontend code.
With Mateu 3.0.0, released on 15 November 2026, those screens can live inside your Visual Builder app — and the shortest way to show it is one line of HTML.
The whole app, in one element
<mateu-ui base-url="https://museums.ec1.mateu.io" shell="true"></mateu-ui>
Put that on your VB app's root page, instead of whatever was there, and press Preview. What you get is not one screen but the whole app the backend declares: its header, its logo, its menu, and every screen behind the menu — with navigation staying inside the component.
The app in the picture is a public Mateu demo: a museum collection (the Met, SMK and the Cleveland Museum of Art). It is a Mateu app running on a Java server (Spring Boot), and its screens are declared in YAML. Nothing about the component depends on that: the same UI could be declared in Java, C# or Python and served by Spring Boot, Quarkus, Micronaut, Helidon, ASP.NET Core or FastAPI. The component only speaks Mateu's wire protocol.
Open Explore › Artworks and the listing is there — search, sortable columns, saved views, column chooser, selection, a "New artwork" action:
Click a row and the record opens inside the component, with its tabs and previous/next navigation.
Watch it: from an empty workspace to a running app
The whole walkthrough is episode 13 of the "Mateu in N minutes" series:
Step by step
1. Create the web app. In a Visual Builder Studio workspace, create a web application as usual (the default template is fine).
2. Download the component. Every Mateu release carries a zip, mateu-ui-<version>.zip. For this one, take it from the v3.0.0 release.
3. Import it. In the Components palette, under Custom (or Integration), choose Import Web Component, and drop the zip. You can also do it from the navigator: Resources › components › Import. The component then appears in the palette as Mateu UI, under Integration.
4. Replace the root page's content with the one element. Open your app's root page (the shell page) in the Page Designer, clear what it has, and drop Mateu UI on it — or write the element in the Code view.
5. Set the Backend base URL. In the Properties panel, set Backend base URL to the Mateu backend (https://museums.ec1.mateu.io for the demo) and App shell to true. Until the base URL is set the component has nothing to load, so an empty box on the canvas is expected. Once it is set, the designer canvas already shows the app:
6. Preview. Run the app. The museums header and menu are there, and every screen works.
Publishing is the usual Visual Builder publish: an environment pointing at your Visual Builder instance, then Publish. The only thing the Mateu backend needs is to allow your app's origin for cross-origin calls (mateu.cors.allowed-origins=https://<your-instance>.oraclecloud.com).
Second use case: one Mateu screen in a page you own
You don't have to hand over the whole app. Leave shell off and give the component a route, and it shows that one screen inside a page of your own flow:
<mateu-ui base-url="https://museums.ec1.mateu.io" route="artworks"></mateu-ui>
Your VB app keeps its shell, its navigation and its URL; Mateu fills one area of one page. Click a row and the record opens inside the component.
Talking to the rest of your page
The component is a regular JET citizen:
-
Properties.
routeis written back as the user navigates, so you can bind it to a page variable with a binding expression (double curly braces).paramsfills a route's placeholders,initial-statepre-fills a form,app-contextpasses the company, fiscal year or whatever context your app keeps (changing it reloads the screen), andnavigation="host"hands every navigation to your page instead of doing it inside the component. -
Events your action chains can listen to:
mateuNavigate(cancelable — send the user to another page of your flow instead),mateuTitle,mateuAction,mateuMessage,mateuReadyandmateuError. -
Identity. The component calls the Mateu backend from the browser, so it passes the identity your app already has:
tokenfor a bearer token, orheaders-provider— a page function asked on every request — for a token that rotates;with-credentialswhen the backend shares your SSO cookie. On a 401 the component fires a cancelablemateu-session-expiredevent so your app can refresh the token and retry.
The fine print
- One
<mateu-ui>per page. - With
shell="true"the menu is drawn as a top band. The backend's user menu and notifications are not drawn inside the component yet. - It is not an iframe and brings no second runtime. It runs on your app's own JET, Redwood theme and Spectra components — which is why a Mateu screen looks like the rest of your app.
- Licensing, plainly. The zip contains only Mateu code, under Apache 2.0. Inside Visual Builder it runs on your app's JET, Redwood and Spectra, under your own Oracle agreement. Nothing of Oracle's is redistributed.
Why it matters
The screen is declared once. The same declaration that fills your Visual Builder page also runs as a standalone web app, in Mateu's phone app and in its desktop app, and an AI agent can describe and operate it over MCP. Your Visual Builder app keeps doing what it does best — the shell, the flows, the integration with the rest of Oracle Cloud — and the forty business screens stop being forty projects.
Get started: mateu.io · the component: Design systems › Oracle Redwood in the docs · release: Mateu v3.0.0 · source: github.com/miguelperezcolom/mateu · videos: the "Mateu in N minutes" playlist on YouTube.
Originally published on Medium.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.


