Configuration

The SDK groups related options so the top-level HeroUIAgent API stays compact.

Resolution order

Every option on this page can be set in two places, and the embed resolves them in this order:

1. SDK defaults — the values documented in the tables below.
2. Your project's saved appearance — whatever the appearance editor holds, fetched when the embed loads.
3. Props on HeroUIAgent — anything you write in code.

The merge runs field by field, not group by group. Overriding one color leaves the rest of the theme — and the launcher, greeting, and composer — exactly as the dashboard defines them:

// Pins the accent. Everything else still comes from the dashboard.
<HeroUIAgent
  getAuthToken={getAuthToken}
  agentId={process.env.NEXT_PUBLIC_HEROUI_AGENT_ID!}
  appearance={{theme: {colors: {accent: "#7c3aed"}}}}
/>

Set remoteConfig to false to skip step 2 entirely and configure the embed only from props.

Three things are always code, because no configuration document can carry them: getAuthToken and agentId (identity), tools and context (functions), and onFeedback (a callback).

Appearance

Each theme color accepts one CSS color for both schemes or {light, dark} values. Unset tokens retain their built-in scheme defaults. Use overlay for dropdown and popover surfaces; use tooltip for tooltip surfaces. Tooltip text contrast is derived automatically.

The panel options apply to floating mode only — a sidebar is docked full-height, and below 640 pixels the panel covers the screen. Both sizes are capped to the viewport, and expanding grows the panel in both directions, never narrower than initialWidth.

<HeroUIAgent
  appearance={{
    shouldCloseOnInteractOutside: false,
    panel: {initialHeight: 620, initialWidth: 480},
  }}
  getAuthToken={getAuthToken}
  agentId={process.env.NEXT_PUBLIC_HEROUI_AGENT_ID!}
/>

Use shouldCloseOnInteractOutside: false or () => false when visitors need to interact with the host page while the floating panel stays open — for example, selecting rows for a client tool. A predicate can keep the panel open only for certain elements, such as (element) => !element.closest('[data-keep-agent-open]'). Escape still closes the panel.

Composer

Permissions

The picker appears in the composer, beside the model picker, and offers three choices: Ask for approval (ask), Approve for me (auto), and Full access (full). A person's selection persists for the conversation.

Two things to know before enabling it:

• It only renders when you declare tools. With no client tools there is nothing to approve, so the picker stays hidden and showPicker has no visible effect.
• It is a privilege boundary. Turning it on lets a visitor select full, which bypasses every needsApproval flag on your declared tools and overrides your defaultMode. Leave it off when any tool can do something irreversible.

Capabilities

Web results are treated as untrusted external content and kept separate from client-tool datasets.

Start screen

Streaming Markdown

Define custom renderer components outside render so their identity remains stable.

import type {AgentMarkdownRendererProps} from "@heroui/agent";

function DiagramRenderer({code, isIncomplete}: AgentMarkdownRendererProps) {
  return <Diagram pending={isIncomplete} source={code} />;
}

<HeroUIAgent
  getAuthToken={getAuthToken}
  markdown={{
    caret: "circle",
    plugins: {renderers: [{component: DiagramRenderer, language: ["diagram"]}]},
  }}
  agentId={process.env.NEXT_PUBLIC_HEROUI_AGENT_ID!}
/>;