@super-assist/react

Package

Field	Value
Install	npm install @super-assist/react
Entries	@super-assist/react, @super-assist/react/devtools, @super-assist/react/styles.css
Peers	react ^19.3.0, react-dom ^19.3.0
Optional peers	@assistant-ui/react-devtools ^1.2.23, for the /devtools entry.

The runtime’s own packages, agents, @cloudflare/ai-chat and ai, are dependencies and install with it.

Entries

Entry	What it holds
@super-assist/react	useAssistedRuntime, the provider, the page, actions, fields and tools, the panel and its parts, the hooks and primitives.
@super-assist/react/devtools	The devtools tab. See the devtools reference.
@super-assist/react/styles.css	The panel’s compiled styles. See the styles reference.

useAssistedRuntime

useAssistedRuntime(options: UseAssistedRuntimeOptions): AssistantRuntime

Connects the panel to a Super Assist project, or to a route of the host’s own, and returns the runtime to pass to AssistedProvider. Pass a key or a basePath, not both.

Option	Type	Description
key	string	The project’s publishable key, pk_ and 32 characters.
agent	string	With a key: an agent’s id, to answer with it instead of the project’s default agent.
user	{ id: string; name?; email? }	With a key: the signed-in user, taken as unverified. Without one, the browser is a visitor.
basePath	string	A route the host authenticates itself, with the Directory under it and each thread under basePath/:id.
host	string	The origin the sockets open on. https://superassist.app with a key, the page’s own origin with a basePath.
thread	string	The thread to open. The hook opens it when it changes.
onThreadChange	(id: string) => void	Called with the open thread’s id whenever it changes, including the hook’s first pick.
onConnectionError	(error: AgentConnectionError) => void	Called when the connection is refused. console.error by default.

• Every message carries system, config and callSettings, read from the model context when it is sent. A continuation after a tool result reuses them from the user’s last message.
• The lent tools go as clientTools with every message and tool result, kept in step with the model context.
• A visitor’s id is kept in localStorage under super-assist:visitor:<key>. Where storage is unavailable, the hook makes a new one.
• The runtime’s thread list is the end user’s threads, most recently active first. The hook opens thread, else the first, and starts a thread when there are none. New thread, rename and delete go to Super Assist.
• Each thread gets its own message store, so switching threads never shows the previous thread’s messages under the new one.
• A refused connection closes with 4401, 4403, 4404 or 4400 and is not retried. See Use the hosted runtime.

Type: UseAssistedRuntimeOptions.

Exports of the main entry

What a page lends

Each export’s props and behavior are on its page under Components.

• AssistedProvider: wraps the app in the runtime and lends what every page shares.
• useAssisted: reads and drives the panel’s open state and the open page’s name.
• AssistedPage: introduces a page, or a dialog over it.
• AssistedAction and useAssistedAction: an element the assistant presses, rings or asks about.
• AssistedInput and useAssistedInput: a native field the assistant fills.
• AssistedField: a control that keeps its value in state.
• useAssistedTool: a tool that runs in the browser.
• ring and useRing: point at one element.
• AssistedCards: the type of the provider’s cards.

AssistedPanel

AssistedPanel is the one-liner, and its members are the parts. Each group’s parts, props and default composition are on its page.

Group	Members
Roots and window	Floating, Sheet, Embedded, Main, Launcher, Trigger, WindowControls
Header	Header, Footer, Icon, Title, PageLine, Close, Devtools
Threads	Threads, ThreadMenu, ThreadSelect, ThreadDrawerToggle, ThreadDrawer, ThreadTitle, NewThread, DeleteThread
Conversation	Conversation, HistorySkeleton, EmptyState, Messages, FollowUps, HandoffOffer, Resolution, ScrollToBottom, ConversationSearch, ConversationSearchToggle
Composer	Composer, Attachments, Input, AddAttachment, Dictate, ModelSelector, Send
Data parts	SettingsToggle, SettingsPanel, ContextDisplay, ContextBreakdown, QuotaBanner

Types: AssistedPanelProps, AssistedPanelFloatingProps, AssistedPanelSheetProps, AssistedPanelEmbeddedProps, AssistedPanelOptions, AssistedPanelWindowProps, ThreadComponents.

Runtime, hooks and primitives

Export	Kind	Description
useAui	Hook	The client that acts on the runtime: aui.threads, aui.thread, aui.composer.
useAuiState	Hook	Selects from the runtime’s state, s.thread and s.threads, and re-renders on change.
useAuiEvent	Hook	Subscribes to one of the runtime’s events.
AuiIf	Component	Renders its children while a condition on the state holds.
AssistantRuntimeProvider, AuiProvider	Component	Provide a runtime, and a client over it. AssistedProvider renders the first for you.
tool, makeAssistantTool	Function	Define a tool outside useAssistedTool.
ThreadPrimitive, MessagePrimitive, ComposerPrimitive, ActionBarPrimitive, BranchPickerPrimitive, AttachmentPrimitive, ErrorPrimitive, SuggestionPrimitive, ThreadListPrimitive, ThreadListItemPrimitive	Components	Unstyled building blocks with the panel’s behavior. See Make your own part.

Type: AssistantRuntime.

The panel’s pieces

The components the parts are built from. They take their data as props, for parts of your own that keep the panel’s look.

Export	What it is
ThreadList	The runtime’s threads with a New Thread button, as Threads and the drawer show them.
ModelSelector, type ModelOption	The model picker, controlled by models, value and onValueChange.
EmptyState, EmptyStateGreeting, EmptyStateSuggestions, EmptyStateSuggestion	The empty state’s layout.
ConversationSearch, type SearchHit	The search box over a conversation.
ThreadSearch, type SearchableThread	The searchable thread list in the menu.
StoppedRun	The stopped reply’s card.
ApprovalCard, type ApprovalState	The confirm card’s look.
OptionList, type OptionListOption	The choices card’s look.
DataTable, types DataTableColumn, DataTableRow	The table card’s look.
SpecSheet, type SpecRow	The spec card’s look.
ComparisonCard, type ComparisonOption	The comparison card’s look.
Sources, type SourcePassage	The sources card’s look.
SettingsPanel, type SettingToggle	The settings’ look.
ContextBreakdown, type ContextSegment	The breakdown’s look.
QuotaBanner	The quota banner.
LauncherBubble, Suggestions, TooltipIconButton, ComposerTriggerPopover	A launcher bubble, a row of suggestions, an icon button with a tooltip, and the slash-command popover.

The parts under AssistedPanel read the panel’s state. These do not: pass them their data.

Types of the rest: AssistedProviderProps, AssistedPageProps, AssistedActionProps, AssistedActionOptions, AssistedInputProps, AssistedInputOptions, AssistedFieldProps, AssistedFieldOption, AssistedTool, AssistedToolFailure, RingOptions, each described with its component or hook.