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 vs 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#

Low-level provider that sets up the message context for a specific message by index. Used internally by ThreadPrimitive.Messages.

<ThreadPrimitive.MessageByIndex index={0}>
  {/* content rendered with message context */}
</ThreadPrimitive.MessageByIndex>

Suggestions#

Renders all thread suggestions using a provided component. Each suggestion is wrapped in a SuggestionByIndexProvider context.

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

SuggestionByIndex#

Low-level provider that sets up the suggestion context for a specific suggestion by index. Used internally by ThreadPrimitive.Suggestions.

<ThreadPrimitive.SuggestionByIndex index={0}>
  <SuggestionPrimitive.Title />
</ThreadPrimitive.SuggestionByIndex>

Suggestion#

Renders a suggestion button. Uses Ink Box + Text.

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

Loading#

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

Composable loading UI for active runs. LoadingPrimitive.Root only renders
while the current thread is running, so it pairs naturally with status rows in
terminal chat layouts.

<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. Supports the existing ink-spinner path plus a few
built-in text-based variants for more terminal-native styles.

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:

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 will 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 using the provided component configuration.

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

AddAttachment#

Triggers attachment addition.

<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#

Low-level provider that sets up the attachment context for a specific attachment by index. Used internally by ComposerPrimitive.Attachments.

<ComposerPrimitive.AttachmentByIndex index={0}>
  <AttachmentPrimitive.Name />
</ComposerPrimitive.AttachmentByIndex>

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 via a components prop. 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#

Low-level provider that sets up the part context for a specific message part by index. Used internally by MessagePrimitive.Parts.

<MessagePrimitive.PartByIndex index={0}>
  {/* content rendered with part context */}
</MessagePrimitive.PartByIndex>

AttachmentByIndex#

Low-level provider that sets up the attachment context for a specific message attachment by index. Used internally by MessagePrimitive.Attachments.

<MessagePrimitive.AttachmentByIndex index={0}>
  <AttachmentPrimitive.Name />
</MessagePrimitive.AttachmentByIndex>

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 using the provided component configuration.

<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 (.pdf, .png, …) when the name has one. Falls back to the attachment type (e.g. image, document) otherwise, and finally to file. 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 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 using a provided components map. Shared from @assistant-ui/core/react.

<ChainOfThoughtPrimitive.Root>
  <ChainOfThoughtPrimitive.AccordionTrigger>
    <Text dimColor>[Toggle reasoning]</Text>
  </ChainOfThoughtPrimitive.AccordionTrigger>
  <ChainOfThoughtPrimitive.Parts>
    {({ part }) => part.type === "text" ? <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={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 for easy diff rendering. 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. The existing prefixes, line numbers, folding, and primitive API surface stay the same. 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 diff context to child components. Parses the patch or computes the diff from old/new file content.

<DiffPrimitive.Root
  patch={patchString}
  oldFile={{ content: oldContent, name: "file.txt" }}
  newFile={{ content: newContent, name: "file.txt" }}
  {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 patch={patchString}>
  <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-5.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; reach for 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.