Levee

Multi-stage guided workflow components with a rail, lock items, and conversation—for strategy flows, onboarding, and goal-directed AI.

Component levee-brand-strategy not found in registry.

Demos (UI only, no backend)

The following demo shows different ways to use Levee: full workflow (form then chat), form-only stage, chat-only stage, and rail with lock checklist. All run in the browser with no API calls.

Overview

Levee is a set of React components for staged, goal-directed workflows. You provide a list of stages (each with id, title, lock items, and mode). The root Levee wraps everything in a provider; the rail shows progress and stage status; the stage view shows the active stage (form, chat, or synthesis). The agent (or completion logic) marks lock items satisfied; the stage does not advance until those criteria are met. Use Levee for strategy flows, onboarding, or any process with a defined "done."

Installation

Levee is part of AI Elements. It is not a CLI-installable UI block. Install the AI SDK and import from the ai-elements package:


pnpm add ai @ai-sdk/openai

import {
  Levee,
  LeveeRail,
  LeveeStageCollectedData,
  LeveeStageHeader,
  LeveeStageLockChecklist,
  LeveeStageView,
  useLevee,
} from "@/components/ai-elements/levee"

For the progress ring used inside the rail and lock checklist, the component uses LeveeProgressRing from @/components/ai-elements/levee-progress internally; you only need to import from levee for the public API above.

Core components

Export	Purpose
`Levee`	Root layout and provider; takes `config`, `allowRevisit`, `onComplete`, etc.
`useLevee`	Hook to read and update stage state (stages, activeStageIndex, updateLockItems, advanceStage, etc.).
`LeveeRail`	Sidebar listing all stages with status and progress.
`LeveeRailItem`	Single stage row (used inside LeveeRail).
`LeveeStageView`	Main area for the active stage; renders children and the interstitial overlay.
`LeveeStageHeader`	Stage title, description, and sidebar toggle.
`LeveeStageSplit`	Optional resizable split (chat + context panel).
`LeveeStageChat`	Flex column container for chat content.
`LeveeConversation`	Scrollable conversation area with scroll-to-bottom button.
`LeveeStageForm`	Renders initial input fields (from config) in the context panel.
`LeveeStageFormView`	Full form-stage layout (fields plus confirm message).
`LeveeStageLockChecklist`	Lock items list and progress ring.
`LeveeStageCollectedData`	Key-value display of collected data for a stage.
`LeveeStageContextPanel`	Wrapper for context content (checklist, data, form).
`LeveeInterstitial`	"Stage complete" overlay shown between stage transitions.

Types

LeveeStageConfig: id, title, description, objective, mode? (one of "form", "chat", "synthesis"), lockItems, initialInputs, agentInstructions, tools, maxSteps?.
LeveeStageState: id, status, phase, formData, collectedData, lockItems, lockPercentage, summary?.
LeveeLockItem: id, label, satisfied.
LeveeInputField: id, label, type (e.g. text, textarea, select, multiselect, number), placeholder?, description?, required?, options?.

Full TypeScript definitions live in @/components/ai-elements/levee.

Usage

Minimal structure: wrap with Levee, put LeveeRail and the active stage content in LeveeStageView. Use useLevee() inside children to drive chat, forms, and lock updates.

import type { LeveeStageConfig } from "@/components/ai-elements/levee"
 
const stages: LeveeStageConfig[] = [
  {
    id: "intro",
    title: "Intro",
    description: "Get started",
    objective: "Collect basic info",
    mode: "form",
    lockItems: [{ id: "done", label: "Info collected", satisfied: false }],
    initialInputs: [{ id: "name", label: "Name", type: "text" }],
    agentInstructions: "Confirm the user's input and mark the stage complete.",
    tools: {},
  },
  {
    id: "chat",
    title: "Discussion",
    description: "Chat stage",
    objective: "Discuss goals",
    mode: "chat",
    lockItems: [{ id: "goals", label: "Goals captured", satisfied: false }],
    initialInputs: [],
    agentInstructions: "Ask about goals and mark the lock when satisfied.",
    tools: { askTextInput: true, askMultipleChoice: true },
  },
]
 
export function MyLeveeFlow() {
  return (
    <Levee
      config={stages}
      allowRevisit
      onComplete={(s) => console.log("Done", s)}
    >
      <LeveeRail>
        <LeveeSidebarContent />
      </LeveeRail>
      <LeveeStageView>
        <LeveeStageHeader />
        <LeveeStageChat>
          <LeveeConversation>{/* messages */}</LeveeConversation>
          {/* PromptInput or custom input */}
        </LeveeStageChat>
      </LeveeStageView>
    </Levee>
  )
}
 
function LeveeSidebarContent() {
  const { stages, activeStageIndex } = useLevee()
  const active = stages[activeStageIndex]
  if (!active) return null
  return (
    <>
      <LeveeStageLockChecklist
        items={active.lockItems}
        percentage={active.lockPercentage}
      />
      <LeveeStageCollectedData data={active.collectedData} />
    </>
  )
}

For a full implementation (API route, tool views, form and synthesis stages), see the Levee brand strategy pro block.

Props

Levee

Prop	Type	Default	Description
`config`	`LeveeStageConfig[]`	required	Stage definitions.
`allowRevisit`	`boolean`	`false`	Whether completed stages can be revisited.
`activeStageIndex`	`number`	—	Controlled current stage index.
`defaultActiveStageIndex`	`number`	`0`	Initial stage when uncontrolled.
`onActiveStageIndexChange`	`(index: number) => void`	—	Called when the active stage changes.
`onComplete`	`(stages: LeveeStageState[]) => void`	—	Called when all stages are locked.

Also accepts div props (e.g. className).

LeveeRail

Prop	Type	Default	Description
`compact`	`boolean`	`false`	When true, narrow rail (icons only).

Also accepts aside props. Children (e.g. lock checklist, collected data) render below the stage list when not compact.

LeveeStageLockChecklist

Prop	Type	Description
`items`	`LeveeLockItem[]`	Lock items and their satisfied state.
`percentage`	`number`	0–100 lock progress.

LeveeStageCollectedData

Prop	Type	Description
`data`	`Record<string, unknown>`	Key-value data collected in the stage.

AI Elements — Chat, message, and prompt components used with Levee.
On the Design of Levee — Design context and why staged workflows.
Levee brand strategy pro block — Full example with API, tool views, and multiple stage modes.

Button Group AI

On This Page

Demos (UI only, no backend)Overview Installation Core components Types Usage Props Levee LeveeRail LeveeStageLockChecklist LeveeStageCollectedData Related

Join The Beta

Copy and Paste 86+
ai sdk patterns.

Get early access pricing and shape the future of the product.

"use client"; import * as React from "react"; import type { LeveeStageConfig } from "@/components/ai-elements/levee"; import { Levee, LeveeConversation, LeveeRail, LeveeStageChat, LeveeStageCollectedData, LeveeStageFormView, LeveeStageHeader, LeveeStageLockChecklist, LeveeStageView, useLevee, } from "@/components/ai-elements/levee"; import { Button } from "@/components/ui/button"; import { Input } from "@/components/ui/input"; import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"; import { Textarea } from "@/components/ui/textarea"; const demoStages: LeveeStageConfig[] = [ { id: "intro", title: "Intro", description: "Tell us a bit about yourself", objective: "Collect name and goal", mode: "form", lockItems: [ { id: "name", label: "Name provided", satisfied: false }, { id: "goal", label: "Goal captured", satisfied: false }, ], initialInputs: [ { id: "name", label: "Name", type: "text", placeholder: "Your name", required: true, }, { id: "goal", label: "Goal", type: "textarea", placeholder: "What do you want to achieve?", }, ], agentInstructions: "Confirm and advance.", tools: {}, }, { id: "chat", title: "Discussion", description: "Quick chat stage", objective: "Capture preferences", mode: "chat", lockItems: [ { id: "prefs", label: "Preferences captured", satisfied: false }, ], initialInputs: [], agentInstructions: "Ask and complete.", tools: {}, }, ]; function FullWorkflowDemo() { return ( <div className="h-[400px] overflow-hidden rounded-lg border"> <Levee allowRevisit config={demoStages} onComplete={() => {}}> <LeveeRail> <DemoSidebarContent /> </LeveeRail> <DemoWorkspace /> </Levee> </div> ); } function DemoSidebarContent() { const { stages, activeStageIndex } = useLevee(); const active = stages[activeStageIndex]; if (!active) return null; return ( <> <LeveeStageLockChecklist items={active.lockItems} percentage={active.lockPercentage} /> <LeveeStageCollectedData data={active.collectedData} /> </> ); } function DemoWorkspace() { const { config, stages, activeStageIndex, updateFormData, updateLockItems, advanceStage, } = useLevee(); const activeStage = config[activeStageIndex]; const activeState = stages[activeStageIndex]; const [formValues, setFormValues] = React.useState<Record<string, unknown>>( {} ); const [chatMessages, setChatMessages] = React.useState< Array<{ role: "user" | "assistant"; text: string }> >([ { role: "assistant", text: "What matters most to you for this project?" }, ]); const [chatInput, setChatInput] = React.useState(""); if (!(activeStage && activeState)) return null; const isForm = activeStage.mode === "form"; const isChat = activeStage.mode === "chat"; const handleFormSubmit = () => { const summary = "Intro complete."; const data = { name: formValues.name, goal: formValues.goal }; updateLockItems( activeStageIndex, activeState.lockItems.map((item) => ({ ...item, satisfied: true })), summary ); advanceStage(summary, data); }; const handleChatSubmit = (e: React.FormEvent) => { e.preventDefault(); if (!chatInput.trim()) return; setChatMessages((prev) => [ ...prev, { role: "user", text: chatInput }, { role: "assistant", text: "Thanks. I've got enough to complete this stage.", }, ]); setChatInput(""); }; const handleCompleteChatStage = () => { updateLockItems( activeStageIndex, activeState.lockItems.map((item) => ({ ...item, satisfied: true })), "Discussion complete." ); advanceStage("Discussion complete.", { preferences: "Captured from chat" }); }; return ( <LeveeStageView> <LeveeStageHeader /> {isForm && ( <LeveeStageFormView confirmationText="" fields={activeStage.initialInputs} isSubmitting={false} onFieldChange={(fieldId, value) => { setFormValues((prev) => ({ ...prev, [fieldId]: value })); updateFormData(activeStageIndex, { [fieldId]: value }); }} onSubmit={handleFormSubmit} values={formValues} /> )} {isChat && ( <LeveeStageChat className="h-[calc(100%-57px)]"> <LeveeConversation className="h-full pb-2"> <div className="space-y-4 pb-4"> {chatMessages.map((msg, i) => ( <div className={ msg.role === "user" ? "flex justify-end" : "flex justify-start" } key={i} > <div className={ msg.role === "user" ? "rounded-lg bg-primary px-3 py-2 text-primary-foreground text-sm" : "rounded-lg bg-muted px-3 py-2 text-sm" } > {msg.text} </div> </div> ))} </div> </LeveeConversation> <div className="border-t px-4 py-3"> <form className="flex gap-2" onSubmit={handleChatSubmit}> <Input className="flex-1" onChange={(e) => setChatInput(e.target.value)} placeholder="Type a message..." value={chatInput} /> <Button type="submit">Send</Button> </form> <Button className="mt-2 w-full" onClick={handleCompleteChatStage} size="sm" variant="secondary" > Complete stage (demo) </Button> </div> </LeveeStageChat> )} </LeveeStageView> ); } function FormOnlyDemo() { const singleFormStage: LeveeStageConfig[] = [ { ...demoStages[0], lockItems: [ { id: "name", label: "Name provided", satisfied: true }, { id: "goal", label: "Goal captured", satisfied: false }, ], }, ]; return ( <div className="h-[340px] overflow-hidden rounded-lg border"> <Levee config={singleFormStage}> <LeveeRail /> <LeveeStageView> <LeveeStageHeader /> <FormOnlyContent /> </LeveeStageView> </Levee> </div> ); } function FormOnlyContent() { const { config, stages, activeStageIndex, updateFormData, updateLockItems, advanceStage, } = useLevee(); const activeStage = config[activeStageIndex]; const activeState = stages[activeStageIndex]; const [values, setValues] = React.useState<Record<string, unknown>>({}); if (!(activeStage && activeState)) return null; return ( <LeveeStageFormView confirmationText="" fields={activeStage.initialInputs} isSubmitting={false} onFieldChange={(fieldId, value) => { setValues((prev) => ({ ...prev, [fieldId]: value })); updateFormData(activeStageIndex, { [fieldId]: value }); }} onSubmit={() => { updateLockItems( activeStageIndex, activeState.lockItems.map((item) => ({ ...item, satisfied: true })), "Done" ); advanceStage("Done", values); }} values={values} /> ); } function ChatOnlyDemo() { const singleChatStage: LeveeStageConfig[] = [demoStages[1]]; return ( <div className="h-[340px] overflow-hidden rounded-lg border"> <Levee config={singleChatStage}> <LeveeRail /> <LeveeStageView> <LeveeStageHeader /> <ChatOnlyContent /> </LeveeStageView> </Levee> </div> ); } function ChatOnlyContent() { const { activeStageIndex, advanceStage, stages, updateLockItems } = useLevee(); const activeState = stages[activeStageIndex]; const [messages, setMessages] = React.useState< Array<{ role: "user" | "assistant"; text: string }> >([{ role: "assistant", text: "This is a chat-stage demo. No backend." }]); const [input, setInput] = React.useState(""); if (!activeState) return null; return ( <LeveeStageChat className="h-[calc(100%-57px)]"> <LeveeConversation className="h-full pb-2"> <div className="space-y-4 pb-4"> {messages.map((msg, i) => ( <div className={ msg.role === "user" ? "flex justify-end" : "flex justify-start" } key={i} > <div className={ msg.role === "user" ? "rounded-lg bg-primary px-3 py-2 text-primary-foreground text-sm" : "rounded-lg bg-muted px-3 py-2 text-sm" } > {msg.text} </div> </div> ))} </div> </LeveeConversation> <div className="border-t px-4 py-3"> <form className="flex gap-2" onSubmit={(e) => { e.preventDefault(); if (input.trim()) { setMessages((prev) => [ ...prev, { role: "user", text: input }, { role: "assistant", text: "Got it (demo only, no API)." }, ]); setInput(""); } }} > <Input className="flex-1" onChange={(e) => setInput(e.target.value)} placeholder="Message..." value={input} /> <Button type="submit">Send</Button> </form> <Button className="mt-2 w-full" onClick={() => { updateLockItems( activeStageIndex, activeState.lockItems.map((item) => ({ ...item, satisfied: true, })), "Done" ); advanceStage("Done", {}); }} size="sm" variant="secondary" > Complete stage (demo) </Button> </div> </LeveeStageChat> ); } function RailAndChecklistDemo() { const [activeIndex, setActiveIndex] = React.useState(0); return ( <div className="h-[300px] overflow-hidden rounded-lg border"> <Levee activeStageIndex={activeIndex} allowRevisit config={demoStages} onActiveStageIndexChange={setActiveIndex} > <LeveeRail compact={false}> <RailChecklistContent /> </LeveeRail> <div className="flex flex-1 items-center justify-center bg-muted/20 text-muted-foreground text-sm"> Rail + lock checklist + collected data (no main content in this demo) </div> </Levee> </div> ); } function RailChecklistContent() { const { stages, activeStageIndex } = useLevee(); const active = stages[activeStageIndex]; const mockCollectedData: Record<string, unknown> = { name: "Jane", goal: "Ship a great product", }; if (!active) return null; return ( <> <LeveeStageLockChecklist items={active.lockItems} percentage={active.lockPercentage} /> <LeveeStageCollectedData data={ Object.keys(active.collectedData).length > 0 ? active.collectedData : mockCollectedData } /> </> ); } export function LeveeDemo() { return ( <div className="space-y-6"> <div className="space-y-2"> <h3 className="font-medium text-sm">Levee — UI demos (no backend)</h3> <p className="text-muted-foreground text-xs"> Different ways to use the Levee components: full workflow, form only, chat only, and rail with lock checklist. </p> </div> <Tabs defaultValue="full"> <TabsList className="w-full justify-start"> <TabsTrigger value="full">Full workflow</TabsTrigger> <TabsTrigger value="form">Form stage</TabsTrigger> <TabsTrigger value="chat">Chat stage</TabsTrigger> <TabsTrigger value="rail">Rail + checklist</TabsTrigger> </TabsList> <TabsContent className="mt-4" value="full"> <FullWorkflowDemo /> </TabsContent> <TabsContent className="mt-4" value="form"> <FormOnlyDemo /> </TabsContent> <TabsContent className="mt-4" value="chat"> <ChatOnlyDemo /> </TabsContent> <TabsContent className="mt-4" value="rail"> <RailAndChecklistDemo /> </TabsContent> </Tabs> </div> ); } export LeveeDemo;