# AI side panel

> An assistant docked beside a page that streams answers, pulls context chips from it, and applies changes with a highlight.

- Type: Block
- Page: https://uiarc.dev/components/blocks/ai-side-panel
- Markdown: https://uiarc.dev/components/blocks/ai-side-panel/markdown

- Access: Arc Pro
- Registry id: `ai-side-panel`
- Source file: `registry/blocks/ai-side-panel/ai-side-panel.tsx`
- Built from: Text stream, Button, Avatar, Tooltip
- Keywords: ai assistant, copilot, side panel, chat, streaming, context chips, suggested actions, llm, sidebar assistant

Use this to add an assistant to a document, project or record page. Pass onAsk to call your model with the question, the selected context ids and the page, stream the text it returns, and apply the proposed changes through onPageChange; answers in the preview are scripted.

## When to use

- An assistant next to a document or project page.
- AI suggestions that change structured data after approval.
- Copilot style help that can go full screen for longer work.

## When not to use

- A standalone chat app; use ai-chat.
- A single prompt box; use ai-composer.
- Showing an autonomous agent's steps; use agent-run.

## Installation

AI side panel is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ai-side-panel
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
import { AiSidePanel } from "@/components/arc/blocks/ai-side-panel/ai-side-panel";

export function PlanPage({ plan }) {
  return (
    <AiSidePanel
      defaultPage={plan}
      onAsk={async (question, context, page) => {
        const res = await fetch("/api/assistant", { method: "POST", body: JSON.stringify({ question, context, page }) });
        return res.json(); // { text, actions: [{ id, label, detail, change }] }
      }}
      onPageChange={savePlan}
    />
  );
}
```

## API reference

### AiSidePanel

An assistant docked beside a page. Context chips come from the page (select a milestone and its chip flies into the composer), answers stream word by word through TextStream, and suggested actions change the page with a highlight on exactly what changed. The panel expands into a focused full view with one continuous layout morph.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultPage` | `PlanPage` | `sample plan` | The page the assistant reads and edits: title, status, lead, target, intro, milestones and notes. |
| `onPageChange` | `(page: PlanPage) => void` | – | Called after every applied or undone action. |
| `onAsk` | `(question: string, context: string[], page: PlanPage) => ScriptedAnswer \| Promise<ScriptedAnswer>` | `scripted sample` | Answers a question with text and suggested actions. context holds the selected milestone ids. The block streams the text. |
| `prompts` | `string[]` | `three prompts` | Suggested prompts in an empty thread. |
| `defaultMode` | `"closed" \| "docked" \| "full"` | `"docked"` | Panel state on mount. |
| `className` | `string` | – | Extra class on the root. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Cmd/Ctrl + J | Opens or closes the assistant while focus is inside the app. |
| Enter | Sends the message; Shift + Enter adds a line. |
| Escape | Returns from the focused view to the dock. |

## Accessibility

- The panel is a labelled complementary region; the expand button reports its state with aria-pressed.
- Streamed text keeps the full answer in the accessibility tree through TextStream and the thread is a polite live region.
- Each suggested action names the change in its label; applied actions become an undo button with a specific name.
- The page is hidden from assistive technology while the focused view covers it.

## Motion

- The panel's box springs between dock and focus on the smooth spring, so the thread reflows continuously instead of jumping.
- Context chips travel from the table row into the composer with shared layout ids, and back when removed.
- Applying an action from the focused view docks the panel first, then washes the changed element and scrolls it into view.
- Reduced motion swaps travel for instant changes and shortens the highlight.

## Responsive behavior

- Below 720px the dock covers the page like a sheet and the focused view is hidden.
- The milestones table compacts by container width, not viewport width.

## Performance

- Only the panel box animates layout; the page reflows once per frame during open and close.
- Streaming updates one message; earlier messages do not re-render their words.

## Notes for AI

- Choose this to add an assistant to a record, document or project page where answers should become edits.
- Return actions as data (PageChange) rather than prose so people approve each change; every action is undoable.
- Replace the scripted answers with streamed tokens from your model; keep the context ids so the model knows what the person selected.

## Related

- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A complete AI chat with streamed markdown answers, folding reasoning, tool chips, citations, and a model switcher.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): A focused assistant thread where messages lift out of the composer and replies stream in.
- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A live AI agent run: steps stream in, tool calls expand, a diff waits for approval, and it all folds into a result.

## Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt