AI Panel

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add ai-panel

Usage#

The panel fills its container (h-full) and owns the scroll: only the body scrolls, while the header and composer stay pinned. Give it a sized frame when docking it in a page.

Anatomy#

import {
  AIPanel,
  AIPanelHeader,
  AIPanelHeading,
  AIPanelTitle,
  AIPanelDescription,
  AIPanelActions,
  AIPanelAction,
  AIPanelExpandToggle,
  AIPanelBody,
  AIPanelFooter,
} from "@/components/ui/ai-panel"

<AIPanel>
  <AIPanelHeader>
    <AIPanelHeading>
      <AIPanelTitle />
      <AIPanelDescription />
    </AIPanelHeading>
    <AIPanelActions>
      <AIPanelExpandToggle />
      <AIPanelAction />
    </AIPanelActions>
  </AIPanelHeader>
  <AIPanelBody />
  <AIPanelFooter />
</AIPanel>

Window modes (split & floating)#

The panel can manage its own window, Notion/Edge-style. Beyond the embedded inline default, it has two windowed views: split (a full-height rail pinned to the right edge, the split-screen assistant) and floating (a compact window hovering bottom-right). Drop an AIPanelExpandToggle in the header to flip between them; it swaps its own icon and label with the view. These modes are non-modal: the page stays interactive, so closing is the host's call (render the panel behind a launcher). The view is controllable via view / defaultView / onViewChange.

Inside an app frame (anchor)#

By default the split and floating windows pin to the browser window (fixed, sized in dvh). When the assistant lives inside an app frame instead (a tablet window, a device mock, a dashboard pane) pass anchor="container": the panel positions itself absolute against the nearest positioned ancestor and sizes the rail and the window in % of it, so it travels and scales with the frame. Give the frame relative overflow-hidden. The AIPanelExpandToggle morphs between the two exactly as it does on the viewport, and the docked rail draws only its inner border.

The example also hands the scroll to the thread: <AIPanelBody scrollable={false}> becomes a fixed column and the Conversation filling it scrolls, so a ConversationScrollButton can float over its bottom edge. Scroll up in the thread to see it.

As an overlay (Drawer)#

Because it's pure layout, the same panel drops straight into a DrawerContent for a slide-in assistant: the Drawer brings the trigger, scrim, focus trap, and animation. Hide the Drawer's own close (showClose=false) and put a close action in the panel header instead. An overlay is never a dead end: keep a minimize to window action that pops the panel out to a floating window (and back), so the assistant can ride along while the user keeps working.

Empty state#

With no messages yet, center a greeting and a few starters in the body. The body is a plain flex region, so a centered welcome composes with no extra parts. For genuine no-content moments (no history, no results, offline), reach for the canonical EmptyState instead: see below.

No content & error states#

Beyond the welcome state, an assistant hits real no-content moments: an empty history, a search that finds nothing, a dropped connection. Because the body is a plain flex region, drop the canonical EmptyState straight in. density="compact" fits the in-panel scale, and variant re-themes the media and action for an error (destructive) versus a neutral zero state (default).

API reference#

FAQ#