Skip to main content
Looking for install steps? See the Quickstart for the one-command shadcn install.
This page covers what the Aomi widget gives you, how it slots into a Next.js app, and how to decide between the widget and the headless library.

​
When to use the widget

Use the widget whenUse the headless library when
You want a production-ready chat UI in minutesYou need a fully custom UI
You’re already on shadcn / TailwindYou’re not using shadcn
Standard layout (sidebar + thread + composer) works for youYou need a non-standard layout
You want to edit source files when neededYou want to compose from primitives
→ Headless Library covers the alternative path.

​
What the widget gives you

  • Full chat surface: sidebar with threads, message composer, streaming thread view.
  • ControlBar: model selector, app selector, API key input, wallet connect, network select.
  • Wallet pipeline: Para-backed connect, wagmi-compatible signing, simulation-first transaction handling.
  • Compound component API: drop in only the pieces you want.
  • Owned source: components are copied into your repo via shadcn; edit anything.

​
Anatomy

your-app/
├── components/
│   ├── aomi-frame.tsx          ← Main shell (Root, Header, Composer)
│   ├── control-bar/            ← Model, App, API key, Wallet, Network
│   ├── assistant-ui/           ← Thread, ThreadList, markdown, tools
│   ├── ui/                     ← shadcn primitives
│   └── runtime-tx-handler.tsx  ← Runtime transaction handler
└── lib/utils.ts
Three registries feed the install:
SourceWhatWhy
aomi.dev/rCustomized components (AomiFrame, Thread, ThreadList)Aomi-specific features like wallet integration
r.assistant-ui.comUpstream primitives (markdown, tooltips)Receives upstream fixes
ui.shadcn.comPrimitives (Button, Sidebar, Dialog)Standard UI building blocks

​
Where it lives in your app

A typical setup mounts AomiFrame on a dedicated route: 
// app/chat/page.tsx
import { AomiFrame } from "@/components/aomi-frame";

export default function ChatPage() {
  return (
    <div style={{ height: "100vh" }}>
      <AomiFrame
        backendUrl={process.env.NEXT_PUBLIC_BACKEND_URL!}
        height="100%"
        width="100%"
      />
    </div>
  );
}
For embedded layouts (sidebars, modals, panels), use the compound API.

​
Next steps

Last modified on June 4, 2026