Primitives are thin wrappers around Ink components (Box, Text) that integrate with the assistant-ui runtime. They accept all standard Ink props and add runtime-aware behavior.

Primitives use namespace imports, the same pattern as the web package (e.g. ThreadPrimitive.Root, ComposerPrimitive.Input).

Many primitives share their core logic with @assistant-ui/react via @assistant-ui/core/react. Only the UI layer (Ink instead of DOM) differs.

Thread#

import { ThreadPrimitive } from "@assistant-ui/react-ink";

Root#

Container Box for the thread area.

<ThreadPrimitive.Root>
  {children}
</ThreadPrimitive.Root>

Messages#

Renders the message list with automatic runtime integration. Each message is wrapped in a scoped context so that useAuiState((s) => s.message) works inside the message component.

<ThreadPrimitive.Messages>
  {() => <MyMessage />}
</ThreadPrimitive.Messages>

AuiIf#

Conditional rendering based on assistant state. Replaces the deprecated ThreadPrimitive.Empty, ThreadPrimitive.If, MessagePrimitive.If, and ComposerPrimitive.If.

import { AuiIf } from "@assistant-ui/react-ink";

<AuiIf condition={(s) => s.thread.isEmpty}>
  <Text dimColor>Send a message to get started</Text>
</AuiIf>

<AuiIf condition={(s) => s.thread.isRunning}>
  <Text color="yellow">Generating...</Text>
</AuiIf>

Empty (deprecated)#

Renders children only when the thread has no messages.

<ThreadPrimitive.Empty>
  <Text dimColor>Send a message to get started</Text>
</ThreadPrimitive.Empty>

If (deprecated)#

Conditional rendering based on thread state.

<ThreadPrimitive.If empty>
  <Text>No messages yet</Text>
</ThreadPrimitive.If>

<ThreadPrimitive.If running>
  <Text color="yellow">Generating...</Text>
</ThreadPrimitive.If>

MessageByIndex#

Renders the message at a specific index and sets up its message context. Shared from @assistant-ui/core/react.

<ThreadPrimitive.MessageByIndex
  index={0}
  components={{ Message: MyMessage }}
/>

Suggestions#

Renders all thread suggestions through a children render function. Each suggestion is wrapped in a SuggestionByIndexProvider context.

<ThreadPrimitive.Suggestions>
  {() => <MySuggestion />}
</ThreadPrimitive.Suggestions>

SuggestionByIndex#

Renders the suggestion at a specific index and sets up its suggestion context.

<ThreadPrimitive.SuggestionByIndex
  index={0}
  components={{ Suggestion: MySuggestion }}
/>

Suggestion#

Pressable that sends a fixed prompt or inserts it into the composer. It renders its children and needs no suggestion context.

<ThreadPrimitive.Suggestion
  prompt="What is the weather?"
  send
  <Text>What is the weather?</Text>
</ThreadPrimitive.Suggestion>

Loading#

import { LoadingPrimitive } from "@assistant-ui/react-ink";

Composable loading UI for active runs. LoadingPrimitive.Root only renders
while the current thread is running.

<LoadingPrimitive.Root gap={1}>
  <LoadingPrimitive.Spinner variant="bar" />
  <LoadingPrimitive.Text>Analyzing codebase...</LoadingPrimitive.Text>
  <LoadingPrimitive.ElapsedTime />
</LoadingPrimitive.Root>

This renders a compact status line such as [=== ] Analyzing codebase... (3s)
while the assistant is streaming.

Root#

Runtime-aware Box container that renders children only while
s.thread.isRunning is true.

Spinner#

Animated loader indicator. variant="spinner" uses ink-spinner; the other
variants are built-in text animations.

Text#

Status label rendered as Ink Text.

ElapsedTime#

Elapsed time indicator for the current run. Uses message timing metadata when
available and falls back to a local timer so it still works during manual
testing.

Composer#

import { ComposerPrimitive } from "@assistant-ui/react-ink";

Root#

Container Box for the composer area.

<ComposerPrimitive.Root>
  {children}
</ComposerPrimitive.Root>

Input#

Terminal line editor wired to the composer runtime. Value is managed automatically and supports cursor-aware editing.

<ComposerPrimitive.Input
  submitOnEnter
  multiLine
  placeholder="Type a message..."
  autoFocus
/>

Supported keyboard bindings:

Alt+Up and Alt+Down are left to the application and do not move the input cursor.

Word boundaries and grapheme stepping use Intl.Segmenter, so emoji, accented letters, skin-tone modifiers, ZWJ sequences, and CJK ideographs each move and delete as a single character.

Some bindings depend on terminal capabilities. iTerm2, Windows Terminal, and most Linux terminals emit Alt-letter combinations as Esc-prefixed sequences that Ink decodes as meta-key input; macOS Terminal.app requires enabling "Use Option as Meta key" in its preferences before Alt+B / Alt+F / Alt+D work as expected. Shift+Enter requires a terminal that supports the CSI-u protocol (iTerm2 3.4+, kitty, foot, and similar). Terminals that conflate it with Enter fall back to the submitOnEnter behaviour.

Example with custom submit handling:

<ComposerPrimitive.Input
  multiLine
  submitOnEnter
  onSubmit={(text) => {
    console.log("submit", text);
  }}
/>

Send#

Box that triggers sending the current message. Typically used with a button-like UI.

<ComposerPrimitive.Send>
  <Text color="green">[Send]</Text>
</ComposerPrimitive.Send>

Cancel#

Box that cancels the current run.

<ComposerPrimitive.Cancel>
  <Text color="red">[Stop]</Text>
</ComposerPrimitive.Cancel>

Attachments#

Renders composer attachments through a children render function.

<ComposerPrimitive.Attachments>
  {() => <MyAttachment />}
</ComposerPrimitive.Attachments>

AddAttachment#

Pressable for an attach control. It is disabled while the composer is not editable. It has no press handler and does not accept onPress, so add attachments by calling aui.composer.addAttachment() from your own code.

<ComposerPrimitive.AddAttachment>
  <Text>[Attach]</Text>
</ComposerPrimitive.AddAttachment>

Queue#

Renders all queued composer items. Each item is wrapped in a QueueItemByIndexProvider, so QueueItemPrimitive.* can read item state and call queue actions inside the render prop. Backed by the shared ComposerPrimitiveQueue from @assistant-ui/core/react.

<ComposerPrimitive.Queue>
  {({ queueItem }) => (
    <Box>
      <QueueItemPrimitive.Text />
      <QueueItemPrimitive.Steer>
        <Text color="cyan">[Run Now]</Text>
      </QueueItemPrimitive.Steer>
      <QueueItemPrimitive.Remove>
        <Text color="red">[x]</Text>
      </QueueItemPrimitive.Remove>
    </Box>
  )}
</ComposerPrimitive.Queue>

Quote#

Renders the active composer quote preview. Children are only rendered while s.composer.quote is set, so this acts as both a container and a gate.

<ComposerPrimitive.Quote>
  <Box>
    <Text dimColor>Quoting:</Text>
    <ComposerPrimitive.QuoteText color="gray" />
    <ComposerPrimitive.QuoteDismiss>
      <Text color="red">[x]</Text>
    </ComposerPrimitive.QuoteDismiss>
  </Box>
</ComposerPrimitive.Quote>

QuoteText#

Renders the quoted text from s.composer.quote?.text. Pass children to override the displayed value.

<ComposerPrimitive.QuoteText color="gray" />

QuoteDismiss#

Pressable that clears the active quote by calling aui.composer.setQuote(undefined).

<ComposerPrimitive.QuoteDismiss>
  <Text color="red">[x]</Text>
</ComposerPrimitive.QuoteDismiss>

Conditional Rendering (Composer)#

Use AuiIf for conditional rendering based on composer state:

<AuiIf condition={(s) => s.composer.isEditing}>
  <Text>Currently editing</Text>
</AuiIf>

AttachmentByIndex#

Renders the composer attachment at a specific index and sets up its attachment context.

<ComposerPrimitive.AttachmentByIndex
  index={0}
  components={{ Attachment: MyAttachment }}
/>

If (deprecated)#

Conditional rendering based on composer state. Shared from @assistant-ui/core/react.

<ComposerPrimitive.If editing>
  <Text>Currently editing</Text>
</ComposerPrimitive.If>

<ComposerPrimitive.If dictation>
  <Text>Dictating...</Text>
</ComposerPrimitive.If>

Message#

import { MessagePartPrimitive, MessagePrimitive } from "@assistant-ui/react-ink";

Root#

Container Box for a single message.

<MessagePrimitive.Root>
  {children}
</MessagePrimitive.Root>

Parts#

Renders message content parts through a children render function or a components map. Tool call and data parts automatically render registered toolkit renderers and data UIs (via useAssistantDataUI), falling back to components provided here. Default terminal-safe renderers are provided for text, reasoning, source, image, file, and data parts.

<MessagePrimitive.Parts>
  {({ part }) => {
    if (part.type === "text") return <Text>{part.text}</Text>;
    if (part.type === "tool-call") return <Text dimColor>[Tool: {part.toolName}]</Text>;
    return null;
  }}
</MessagePrimitive.Parts>

Override part rendering with app-owned components when you need richer terminal UI:

<MessagePrimitive.Parts
  components={{
    Image: () => <Text color="cyan">image available</Text>,
    Reasoning: () => null,
    data: {
      by_name: {
        weather_card: ({ data }) => <Text>{data.city}: {data.temperature}</Text>,
      },
    },
  }}
/>

Content (deprecated)#

Renders message content parts using render props. Tool call and data parts automatically render registered toolkit renderers and data UIs (via useAssistantDataUI), falling back to render props if provided.

<MessagePrimitive.Content
  renderText={({ part }) => <Text>{part.text}</Text>}
  renderToolCall={({ part }) => <Text dimColor>[Tool: {part.toolName}]</Text>}
/>

MessagePartPrimitive#

Composable primitives for rendering the current message part inside part context from MessagePrimitive.Parts, MessagePrimitive.PartByIndex, or PartByIndexProvider.

<MessagePrimitive.Parts
  components={{
    Text: () => (
      <>
        <MessagePartPrimitive.Text />
        <MessagePartPrimitive.InProgress>
          <Text color="yellow"> ...</Text>
        </MessagePartPrimitive.InProgress>
      </>
    ),
    File: () => <MessagePartPrimitive.File dimColor />,
  }}
/>

PartByIndex#

Renders the message part at a specific index and sets up its part context.

<MessagePrimitive.PartByIndex
  index={0}
  components={{
    Text: () => <MessagePartPrimitive.Text />,
  }}
/>

AttachmentByIndex#

Renders the message attachment at a specific index and sets up its attachment context.

<MessagePrimitive.AttachmentByIndex
  index={0}
  components={{ Attachment: MyAttachment }}
/>

Quote#

Renders the quote a message was sent with, read from s.message.metadata.custom.quote. Renders nothing when the message carries no quote. Place it above MessagePrimitive.Parts in the user message.

<MessagePrimitive.Quote>
  {({ text }) => <Text dimColor>Replying to: {text}</Text>}
</MessagePrimitive.Quote>

Conditional Rendering (Message)#

Use AuiIf for conditional rendering based on message properties:

<AuiIf condition={(s) => s.message.role === "user"}>
  <Text bold color="green">You:</Text>
</AuiIf>

<AuiIf condition={(s) => s.message.role === "assistant" && s.message.isLast}>
  <Text color="yellow">Thinking...</Text>
</AuiIf>

If (deprecated)#

Conditional rendering based on message properties.

<MessagePrimitive.If user>
  <Text bold color="green">You:</Text>
</MessagePrimitive.If>

<MessagePrimitive.If assistant last>
  <Text color="yellow">Thinking...</Text>
</MessagePrimitive.If>

Attachments#

Renders user message attachments through a children render function.

<MessagePrimitive.Attachments>
  {() => <Text>[attachment]</Text>}
</MessagePrimitive.Attachments>

Attachment#

import { AttachmentPrimitive } from "@assistant-ui/react-ink";

Primitives for rendering individual attachments. Each primitive reads from the current attachment context (provided by ComposerPrimitive.Attachments, ComposerPrimitive.AttachmentByIndex, MessagePrimitive.Attachments, or MessagePrimitive.AttachmentByIndex).

Root#

Container Box for an attachment. Forwards all Box props.

Name#

Text component displaying s.attachment.name.

Thumb#

Text component displaying a short identifier for the attachment. Renders the file extension (such as .pdf or .png) when the name has one, and the attachment type (e.g. image, document) otherwise. Passing children overrides the automatic label.

Status#

Text component rendering the current attachment status from s.attachment.status. Uses the same visual vocabulary as ToolFallback: spinner = uploading, ? = pending action, x = error, || = paused. By default, completed attachments render nothing.

Remove#

Pressable that calls aui.attachment.remove() when activated (Enter or Space while focused). Disabled when not focused or when the disabled prop is set.

<AttachmentPrimitive.Root>
  <AttachmentPrimitive.Thumb />
  <AttachmentPrimitive.Name />
  <AttachmentPrimitive.Status />
  <AttachmentPrimitive.Remove>
    <Text color="red">[x]</Text>
  </AttachmentPrimitive.Remove>
</AttachmentPrimitive.Root>

QueueItem#

import { QueueItemPrimitive } from "@assistant-ui/react-ink";

Primitives for rendering individual queued composer items. Use inside a ComposerPrimitive.Queue render prop, where the queue item context is set up by QueueItemByIndexProvider.

Text#

Renders the queue item's text with Ink <Text>. Pass children to override the displayed value.

<QueueItemPrimitive.Text color="gray" />

Remove#

Pressable that removes the queue item by calling aui.queueItem.remove().

<QueueItemPrimitive.Remove>
  <Text color="red">[x]</Text>
</QueueItemPrimitive.Remove>

Remaining props are forwarded to the underlying Pressable (Ink Box props).

Steer#

Pressable that promotes the queue item to run next by calling aui.queueItem.steer().

<QueueItemPrimitive.Steer>
  <Text color="cyan">[Run Now]</Text>
</QueueItemPrimitive.Steer>

Remaining props are forwarded to the underlying Pressable (Ink Box props).

ActionBar#

import { ActionBarPrimitive } from "@assistant-ui/react-ink";

Copy#

Pressable that copies the message content. Pass a platform clipboard writer through copyToClipboard. Supports function-as-children for copy state feedback.

<InstallCommand npm={["clipboardy"]} />

import clipboard from "clipboardy";

<ActionBarPrimitive.Copy
  copiedDuration={3000}
  copyToClipboard={clipboard.write}
  {({ isCopied }) => <Text>{isCopied ? "[Copied!]" : "[Copy]"}</Text>}
</ActionBarPrimitive.Copy>

Edit#

Pressable that enters edit mode for a message.

<ActionBarPrimitive.Edit>
  <Text>[Edit]</Text>
</ActionBarPrimitive.Edit>

Reload#

Pressable that regenerates an assistant message.

<ActionBarPrimitive.Reload>
  <Text>[Retry]</Text>
</ActionBarPrimitive.Reload>

FeedbackPositive / FeedbackNegative#

Pressable buttons for submitting message feedback.

<ActionBarPrimitive.FeedbackPositive>
  {({ isSubmitted }) => <Text>{isSubmitted ? "[Liked]" : "[Like]"}</Text>}
</ActionBarPrimitive.FeedbackPositive>

<ActionBarPrimitive.FeedbackNegative>
  {({ isSubmitted }) => <Text>{isSubmitted ? "[Disliked]" : "[Dislike]"}</Text>}
</ActionBarPrimitive.FeedbackNegative>

BranchPicker#

import { BranchPickerPrimitive } from "@assistant-ui/react-ink";

Previous / Next#

Pressable buttons to navigate between message branches.

<Box>
  <BranchPickerPrimitive.Previous>
    <Text>{"<"}</Text>
  </BranchPickerPrimitive.Previous>
  <BranchPickerPrimitive.Number />
  <Text>/</Text>
  <BranchPickerPrimitive.Count />
  <BranchPickerPrimitive.Next>
    <Text>{">"}</Text>
  </BranchPickerPrimitive.Next>
</Box>

Number / Count#

Text components displaying the current branch number and total count.

ThreadList#

import { ThreadListPrimitive } from "@assistant-ui/react-ink";

Root#

Container Box for the thread list.

Items#

Renders thread list items with runtime integration.

<ThreadListPrimitive.Items
  renderItem={({ threadId }) => (
    <ThreadEntry threadId={threadId} />
  )}
/>

New#

Pressable that creates a new thread.

<ThreadListPrimitive.New>
  <Text color="green">[New Chat]</Text>
</ThreadListPrimitive.New>

ThreadListItem#

import { ThreadListItemPrimitive } from "@assistant-ui/react-ink";

Root#

Container Box for a thread list item.

Title#

Text component displaying the thread list item title. Shared from @assistant-ui/core/react.

Trigger#

Pressable that switches to the thread.

Delete#

Pressable that deletes the thread.

Archive / Unarchive#

Pressable buttons that archive or unarchive the thread.

<ThreadListItemPrimitive.Root>
  <ThreadListItemPrimitive.Trigger>
    <ThreadListItemPrimitive.Title />
  </ThreadListItemPrimitive.Trigger>
  <ThreadListItemPrimitive.Delete>
    <Text color="red">[x]</Text>
  </ThreadListItemPrimitive.Delete>
</ThreadListItemPrimitive.Root>

Suggestion#

import { SuggestionPrimitive } from "@assistant-ui/react-ink";

Title#

Text component displaying the suggestion title.

Description#

Text component displaying the suggestion label. Despite the component name, this reads from the label field of the suggestion state (not a separate description field).

Trigger#

Pressable that triggers the suggestion action.

<SuggestionPrimitive.Trigger send>
  <SuggestionPrimitive.Title />
</SuggestionPrimitive.Trigger>

ChainOfThought#

import { ChainOfThoughtPrimitive } from "@assistant-ui/react-ink";

Root#

Container Box for chain of thought content.

AccordionTrigger#

Pressable that toggles the collapsed state of the chain of thought.

Parts#

Renders the individual parts of a chain of thought through a children render function. Shared from @assistant-ui/core/react.

<ChainOfThoughtPrimitive.Root>
  <ChainOfThoughtPrimitive.AccordionTrigger>
    <Text dimColor>[Toggle reasoning]</Text>
  </ChainOfThoughtPrimitive.AccordionTrigger>
  <ChainOfThoughtPrimitive.Parts>
    {({ part }) => part.type === "reasoning" ? <Text dimColor>{part.text}</Text> : null}
  </ChainOfThoughtPrimitive.Parts>
</ChainOfThoughtPrimitive.Root>

ToolCall#

import { ToolCallPrimitive } from "@assistant-ui/react-ink";

Fallback#

A built-in component for rendering tool calls with expandable/collapsible output. Includes a spinner for running tools, formatted JSON args and result output, and status icons for completed, errored, or interrupted calls.

<MessagePrimitive.Parts>
  {({ part }) => {
    if (part.type === "tool-call") return <ToolCallPrimitive.Fallback {...part} />;
    return null;
  }}
</MessagePrimitive.Parts>

Diff#

import { DiffPrimitive, DiffView } from "@assistant-ui/react-ink";

Components for rendering code diffs in the terminal.

DiffView#

Pre-composed component that combines all diff primitives. Accepts either a unified diff patch string or old/new file content for inline comparison.

When a replacement is rendered as an equal-length adjacent -/+ run, DiffView also highlights the changed word spans inside those lines. Prefixes, line numbers, and folding are unaffected. This intra-line behavior is internal to DiffView; DiffPrimitive.Line remains a line-level primitive.

// From a patch string
<DiffView
  patch={unifiedDiffString}
  showLineNumbers
  contextLines={3}
  maxLines={50}
/>

// From file contents
<DiffView
  oldFile={{ content: "old text", name: "file.txt" }}
  newFile={{ content: "new text", name: "file.txt" }}
  showLineNumbers
/>

Root#

Container Box that provides parsed diff files to child components. It does not parse a patch or compare file contents; pass already parsed files, or use DiffView to render from a patch string or file contents.

<DiffPrimitive.Root files={files}>
  {children}
</DiffPrimitive.Root>

Header#

Displays file header information including filename(s) and change statistics.

<DiffPrimitive.Header fileIndex={0} />

Content#

Renders the diff content with lines. Supports context folding and line truncation.

<DiffPrimitive.Content
  fileIndex={0}
  showLineNumbers
  contextLines={3}
  maxLines={100}
  renderLine={({ line, index }) => <CustomLine line={line} />}
  renderFold={({ region, index }) => <CustomFold region={region} />}
/>

Line#

Renders an individual diff line with appropriate coloring and indicators.

<DiffPrimitive.Line
  line={parsedLine}
  showLineNumbers
  lineNumberWidth={4}
/>

Stats#

Displays diff statistics (additions and deletions count).

<DiffPrimitive.Stats fileIndex={0} />

Composing with Primitives#

For custom layouts, use the primitives directly:

<DiffPrimitive.Root files={files}>
  <Box flexDirection="column">
    <DiffPrimitive.Header />
    <DiffPrimitive.Stats />
    <DiffPrimitive.Content
      showLineNumbers
      contextLines={2}
    />
  </Box>
</DiffPrimitive.Root>

StatusBar#

import { StatusBarPrimitive } from "@assistant-ui/react-ink";

Primitives for rendering a compact terminal status bar showing run state, model, message count, token usage, and latency. All sub-components read directly from the active thread state.

Root#

Container Box for the status bar. Forwards all Box props; pass gap to space its children.

ModelName#

Text component displaying the current model name. The name is supplied as a prop. The primitive does not infer it from state.

MessageCount#

Text component displaying the number of messages on the current thread, formatted as N msgs by default. Renders nothing when the thread is empty.

TokenCount#

Text component summing metadata.timing.tokenCount across all assistant messages on the thread, formatted with toLocaleString() + " tokens" by default. Renders nothing when the total is 0.

Latency#

Text component displaying metadata.timing.tokensPerSecond from the most recent assistant message, formatted as N tok/s (rounded) by default. Renders nothing when the field is missing.

Status#

Text component reporting the thread's run state. Resolves to "running" while s.thread.isRunning, otherwise inspects the most recent assistant message: "error" when its status is incomplete with reason error, "cancelled" when reason is cancelled, and "idle" for every other case. Pass color (or any Text prop) to style the label.

<StatusBarPrimitive.Root gap={1}>
  <StatusBarPrimitive.Status />
  <StatusBarPrimitive.ModelName name="gpt-6-luna" />
  <StatusBarPrimitive.MessageCount />
  <StatusBarPrimitive.TokenCount />
  <StatusBarPrimitive.Latency />
</StatusBarPrimitive.Root>

TextInput#

import { TextInput } from "@assistant-ui/react-ink";

Store-free, controlled single/multi-line text field. Ink ships no native text input, so this is the terminal equivalent of the DOM <textarea> or React Native's <TextInput>: the editing engine (buffer, grapheme-aware cursor, and the full emacs/arrow keymap) without any runtime or composer coupling. ComposerPrimitive.Input is a thin adapter that wraps TextInput and binds it to the composer store. Use TextInput directly when you need an editable field outside the thread composer (for example, editing a value before confirming an action).

It is controlled on value/onChange, so an external owner can override the text at any time (the buffer absorbs the echo without thrashing the cursor). An owner may also transform the emitted text in onChange (uppercase, mask, reject); the buffer applies the corrected value while keeping the cursor at the edit position, snapped to a grapheme boundary. A replacement that does not respond to an edit (a programmatic set while idle) still places the cursor at the end:

const [command, setCommand] = useState(approval.action.command);

<TextInput
  value={command}
  onChange={setCommand}
  submitOnEnter
  onSubmit={(text) => runEdited(text)}
/>

Keyboard bindings, grapheme handling, and terminal-capability caveats are identical to ComposerPrimitive.Input.