> ## Documentation Index
> Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customization

> Adapt AomiWidget with props, themes, source components, or the headless React library while preserving its runtime behavior.

Start with `AomiWidget`, then take ownership of more of the interface only when your product needs it.

## Choose your customization level

| Level | You own | Aomi provides |
| - | - | - |
| Widget props | Placement and visible controls | Complete UI, runtime, and wallets |
| Themes | Brand colors and visual tokens | Component structure and behavior |
| `AomiFrame` | Component composition | Chat, threads, and wallet components |
| shadcn source | The copied component source | A production starting point |
| Headless library | The complete interface | State, runtime, and React hooks |

## Configure AomiWidget

Use presentation props to fit the widget into a page, panel, or modal.

```tsx theme={null}
<AomiWidget
  applicationId="123"
  apiUrl="https://chat.aomi.dev"
  auth={{ kind: "browser_wallet" }}
  width="100%"
  height="min(780px, calc(100dvh - 160px))"
  showSidebar
  showHeader
  walletPosition="footer"
/>
```

| Prop | Purpose |
| - | - |
| `width`, `height` | Size the widget container |
| `className`, `style` | Add application-specific layout styles |
| `showSidebar` | Show or hide thread navigation |
| `showHeader` | Show or hide the widget header |
| `walletPosition` | Place the wallet control in the header or footer; pass `null` to hide it |
| `wallets` | Limit presented wallets, chains, and networks |
| `persistThread` | Restore the active thread after a reload |

These props change presentation. The Application ID selects the deployed App; action review and wallet execution remain visible client responsibilities.

## Apply themes and styles

Import the default stylesheet once:

```tsx theme={null}
import "@aomi-labs/widget-lib/styles.css";
```

Then override its CSS variables in your application stylesheet. Keep transaction warnings, fees, owner addresses, and confirmation states visually distinct when changing colors.

## Compose with AomiFrame

Use the compound API when the standard widget layout is close to what you need, but you want to rearrange its sections.

```tsx theme={null}
import { AomiFrame } from "@aomi-labs/widget-lib";

<AomiFrame.Root
  backendUrl="https://chat.aomi.dev"
  applicationId="123"
  height="720px"
  showSidebar={false}
>
  <AomiFrame.Header showSidebarTrigger={false} />
  <AomiFrame.Composer
    withControl
    welcomeTitle="How can I help?"
  />
</AomiFrame.Root>;
```

`AomiFrame` provides the chat surface and runtime. If you use it outside `AomiWidget`, your application must supply the surrounding authentication and account integration.

## Own the source with shadcn

Copy the widget components into your repository when you need to change markup or component behavior:

```bash theme={null}
npx shadcn add https://aomi.dev/r/aomi-widget.json
```

Copied components become application code. Review registry updates before overwriting local changes.

## Build a headless UI

Choose the headless library when props, themes, composition, and copied components are not enough. Aomi continues to provide thread, chat, user, event, notification, and wallet-request state. You provide every visible interaction.

### Install the library

```bash theme={null}
npm install @aomi-labs/react @assistant-ui/react
```

### Add the runtime provider

```tsx theme={null}
import { AomiRuntimeProvider } from "@aomi-labs/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AomiRuntimeProvider
      backendUrl="https://chat.aomi.dev"
      applicationId="123"
    >
      {children}
    </AomiRuntimeProvider>
  );
}
```

### Your responsibilities

A headless interface must provide:

* Thread navigation and message rendering.
* Composer, streaming, cancellation, and error states.
* Wallet connection and network selection.
* Transaction-call and fee disclosure.
* Explicit approval and rejection controls.
* Owner and network validation before signing.
* Submitted, confirmed, expired, and failed operation states.

<Warning>
  Returning a generic transaction result is not enough. Your interface must narrow each action by `action.request.kind`, show the exact request, and return the result that kind expects. Prefer `AomiWidget` unless you need to own the full approval experience.
</Warning>

## Hooks

All hooks must run beneath `AomiRuntimeProvider`.

### Chat and threads

| Hook | Purpose |
| - | - |
| `useAomiRuntime` | Unified chat, thread, user, notification, event, and wallet API |
| `useThreadContext` | Low-level thread state and operations |
| `useCurrentThreadMetadata` | Metadata for the active thread |

Read active-thread messages with `useAomiRuntime().getMessages()`.

### User and wallet controls

| Hook | Purpose |
| - | - |
| `useUser` | Canonical user and wallet state |
| `useControl` | Combined App, model, API-key, and secret controls |
| `useApiKey` | API-key state and actions |
| `useAuthEndpoints` | Available Apps and models |
| `usePerThreadControl` | Per-thread App and model selection |

### Events and notifications

| Hook | Purpose |
| - | - |
| `useNotification` | Notice, success, wallet, and error messages |

Read ordered backend events from `useAomiRuntime().events` and the active lifecycle from `turnState`. `pendingActions` contains canonical Actions; narrow on `action.request.kind` before reading its payload. Use the exported TypeScript types as the source of truth for complete signatures and payloads.

## Complete custom UI example

This starter owns message rendering, the composer, cancellation, and the visible wallet-request count:

```tsx theme={null}
"use client";

import { useState, type FormEvent } from "react";
import { useAomiRuntime } from "@aomi-labs/react";

export function CustomChat() {
  const [input, setInput] = useState("");
  const {
    currentThreadId,
    getMessages,
    sendMessage,
    isRunning,
    cancelGeneration,
    pendingActions,
  } = useAomiRuntime();

  const messages = getMessages(currentThreadId);

  async function submit(event: FormEvent) {
    event.preventDefault();
    const text = input.trim();
    if (!text || isRunning) return;
    setInput("");
    await sendMessage(text);
  }

  return (
    <main>
      <section aria-live="polite">
        {messages.map((message, index) => (
          <article key={index} data-role={message.role}>
            <strong>{message.role}</strong>
          </article>
        ))}
      </section>

      <form onSubmit={submit}>
        <input
          value={input}
          onChange={(event) => setInput(event.target.value)}
          disabled={isRunning}
        />
        {isRunning ? (
          <button type="button" onClick={cancelGeneration}>Stop</button>
        ) : (
          <button type="submit">Send</button>
        )}
      </form>

      <p>{pendingActions.length} actions need review</p>
    </main>
  );
}
```

Add an approval component for every action kind your App can produce. Show the calls, signatures, owner, network, simulation evidence, and terminal status available on the request.