Primitives

Primitives are thin wrappers around Ink components (Box, Text, TextInput) 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.

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 prompt 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. Supports function-as-children for copy state feedback.

<ActionBarPrimitive.Copy copiedDuration={3000}>
  {({ 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" />
  <StatusBarPrimitive.MessageCount />
  <StatusBarPrimitive.TokenCount />
  <StatusBarPrimitive.Latency />
</StatusBarPrimitive.Root>