Beyond the Basics: Custom Component Catalogs

The Analogy: Standard A2UI components are like standard Lego bricks (2x4, 1x2). They fit everywhere. Custom Components are like 3D-printed parts. You design them specifically for your spaceship (app), and they fit perfectly.

Why Custom Catalogs?

The Standard Catalog covers 80% of use cases (Buttons, Text, Tables). But for the other 20%, you need power.

• Fintech: A <StockCandleChart />.
• Travel: A <SeatSelector />.
• Maps: A <GoogleMapLocation />.

Instead of trying to “hack” a map out of text boxes, A2UI lets you register Native Components.

How it Works: The “Handshake”

1. Host App: “I have a component called flight-card.”
2. Registry: Adds flight-card to the allowlist.
3. Agent: Sends JSON { "type": "flight-card", "props": { ... } }.
4. A2UI Runtime: Matches the string flight-card to your React function and renders it.

Example: Building a Map Component

1. The React Component

Just a normal React component. No special A2UI code inside.

// components/MapWidget.tsx
 export const MapWidget = ({ lat, lng }) => (
   <GoogleMap center={{ lat, lng }} zoom={12} />
 );

2. The Registry Entry

Tell A2UI that this component exists.

// registry.ts
 const myCatalog = {
   'map-widget': MapWidget
 };

3. The Agent Prompt

Teach the AI how to use it.

 SYSTEM: You can show a map by sending:
 { "type": "map-widget", "props": { "lat": number, "lng": number } }

Security: The Firewall Effect

This is where A2UI shines over “Generated UI”.

• The Agent cannot invent new components.
• If the Agent tries to send <BitcoinMiner />, the A2UI runtime sees it’s not in the registry and blocks it.
• You have total control over what code runs on the user’s device.