Custom ComponentsSoon

HeroUI Agent renders its conversation UI in a hosted, cross-origin iframe. This lets HeroUI ship new components, charts, file renderers, and fixes directly through the hosted runtime.

Because React components cannot cross the iframe boundary, client tools do not accept a custom render function and Markdown does not accept React renderers. A dedicated custom component API for the hosted Agent is in progress. Until it ships, use the hosted component catalog for presentation and client tools for customer-product actions.

What you can build today

Hosted catalog components

Every generated component comes from the validated hosted catalog. Client tools return structured data, and the Agent selects, validates, and renders a compatible component with the embed's theme. See Data Visualization, Display Information, Form Elements, and Actions.

Interactive actions with client tools

Generated component actions use the same client-tool bridge as model-initiated calls. Declare a tool in the customer page and the hosted Agent renders approval, progress, success, and error states while its execute function runs with the customer's authenticated product context.

import {HeroUIAgent, createToolHelper} from "@heroui/agent";
import {z} from "@heroui/agent/zod";

type ProductContext = {
  products: {
    create: (input: {name: string}) => Promise<{id: string; name: string}>;
    open: (id: string) => void;
  };
};

const tool = createToolHelper<ProductContext>();

const tools = [
  tool({
    name: "add_product",
    displayName: "Add product",
    description: "Create a product in the current workspace",
    icon: "add",
    needsApproval: true,
    parameters: z.object({name: z.string().min(1)}),
    execute: ({name}, context) => context.products.create({name}),
  }),
  tool({
    name: "view_product",
    displayName: "View product",
    description: "Open a product in the customer application",
    icon: "view",
    parameters: z.object({id: z.string()}),
    execute: ({id}, context) => {
      context.products.open(id);
      return {opened: true};
    },
  }),
];

<HeroUIAgent
  agentId={process.env.HEROUI_AGENT_ID!}
  context={{products}}
  getAuthToken={getAuthToken}
  tools={tools}
/>;

Only the tool manifest and JSON-safe page context enter the iframe. Tool functions, API clients, routers, state setters, and the rest of context remain in the customer page.

What is planned

The custom component API will let you attach your own UI to a client tool's states, so a domain-specific view can replace the default tool card while the rest of the conversation keeps the hosted catalog. Your component code stays in your application and ships on your own release schedule; the hosted Agent keeps control of the conversation chrome, theming, and security boundary.

Details of the API are not final. If you have a use case that depends on it, tell us through the dashboard so it can shape the design.

Requesting a new hosted visual

If a domain-specific view would be useful to many integrations, it can be added to the hosted catalog and its validated data contract. Once deployed, it becomes available on the next reload.

For action and approval details, see Client Tools. For the available hosted components, see Display Information.