assistant-ui logo/Docs

Directive Text

Render mention directives as inline chips in user messages.

User message
Use Get Weather to check today's forecast in Tokyo.
Another example
Ask Search for recent updates on Calendar.

DirectiveText parses the directive syntax written by ComposerTriggerPopover (default: :type[label]{name=id}) and renders each segment as an inline chip. Use it as the Text component in user messages so the raw directive syntax never shows up.

Getting Started

Add directive-text

npx shadcn@latest add https://r.assistant-ui.com/directive-text.json

This adds /components/assistant-ui/directive-text.tsx with DirectiveText and the createDirectiveText(formatter, options?) factory.

Use in user messages

Pass DirectiveText as the Text component in MessagePrimitive.Parts:

components/assistant-ui/thread.tsx
import { DirectiveText } from "@/components/assistant-ui/directive-text";

const UserMessage = () => (
  <MessagePrimitive.Root>
    <MessagePrimitive.Parts components={{ Text: DirectiveText }} />
  </MessagePrimitive.Root>
);

Keep your markdown renderer (e.g. MarkdownText) for assistant messages — assistants rarely emit directive syntax.

Icons per Directive Type

DirectiveText ships icon-free by default — every parsed segment renders as a plain label chip regardless of its type. To add icons, use the createDirectiveText factory and pass an iconMap that routes each type string to an icon component, plus an optional fallbackIcon for unmapped types:

import { createDirectiveText } from "@/components/assistant-ui/directive-text";
import { unstable_defaultDirectiveFormatter } from "@assistant-ui/react";
import { FileTextIcon, SparklesIcon, UserIcon, WrenchIcon } from "lucide-react";

const DirectiveTextWithIcons = createDirectiveText(
  unstable_defaultDirectiveFormatter,
  {
    iconMap: {
      tool: WrenchIcon,
      user: UserIcon,
      file: FileTextIcon,
    },
    fallbackIcon: SparklesIcon,
  },
);

<MessagePrimitive.Parts components={{ Text: DirectiveTextWithIcons }} />;

A matching iconMap / fallbackIcon option is accepted by ComposerTriggerPopover, where it routes item.metadata.icon strings instead of type — keeping icon configuration consistent across the composer and the rendered message.

Custom Formatter

The default format is :type[label]{name=id}. For a different format, build a custom Unstable_DirectiveFormatter and wrap it with createDirectiveText:

import type { Unstable_DirectiveFormatter } from "@assistant-ui/react";
import { createDirectiveText } from "@/components/assistant-ui/directive-text";

const slashFormatter: Unstable_DirectiveFormatter = {
  serialize: (item) => `/${item.id}`,
  parse: (text) => {
    /* return alternating text / mention segments */
  },
};

const SlashDirectiveText = createDirectiveText(slashFormatter);

Pass the same formatter to the composer trigger's directive={{ formatter }} (or action={{ formatter }}) so insertion and rendering stay consistent.

Customizing the Chip

Because directive-text.tsx is copied into your project, you can also edit it directly — swap the chip styling, read data-directive-id to link to a detail page, or replace the chip wrapper entirely.

API Reference

DirectiveText

A TextMessagePartComponent that parses :type[label]{name=id} directives and renders them as inline chips. Uses the default formatter from @assistant-ui/react and renders chips without icons. For per-type icons, build a component with createDirectiveText(formatter, { iconMap }).

createDirectiveText(formatter, options?)

Factory that returns a TextMessagePartComponent bound to a custom Unstable_DirectiveFormatter.

OptionTypeDescription
iconMapRecord<string, ComponentType<{ className?: string }>>Maps a directive segment's type to an icon rendered inside the chip
fallbackIconComponentType<{ className?: string }>Icon used when no iconMap entry matches. When neither option resolves, the chip renders without an icon.