Nexus UI

Nexus UI

An open-source component library for building AI-powered interfaces. Composable, copy-paste primitives for chat, streaming, and multimodal experiences — built on React, Tailwind CSS v4, and Radix UI.

Components are distributed via the shadcn registry and installed as source code into the user's project.

IMPORTANT: Run CLI commands using the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest — based on the project's packageManager.

Installation

1. Add the registry

Add the Nexus UI registry to the project's components.json:

{
  "registries": {
    "@nexus-ui": "https://nexus-ui.dev/r/{name}.json"
  }
}

2. Add components

npx shadcn@latest add @nexus-ui/prompt-input
npx shadcn@latest add @nexus-ui/model-selector
npx shadcn@latest add @nexus-ui/suggestions
npx shadcn@latest add @nexus-ui/attachments
npx shadcn@latest add @nexus-ui/message
npx shadcn@latest add @nexus-ui/thread
npx shadcn@latest add @nexus-ui/citation
npx shadcn@latest add @nexus-ui/reasoning
npx shadcn@latest add @nexus-ui/text-shimmer
npx shadcn@latest add @nexus-ui/image
npx shadcn@latest add @nexus-ui/feedback-bar
npx shadcn@latest add @nexus-ui/toaster
npx shadcn@latest add @nexus-ui/chain-of-thought
npx shadcn@latest add @nexus-ui/tool
npx shadcn@latest add @nexus-ui/questions

Or install directly via URL (no registry config needed):

npx shadcn@latest add https://nexus-ui.dev/r/prompt-input.json

Components are installed to components/nexus-ui/ by default.

Prerequisites

• React 19+
• Tailwind CSS v4
• TypeScript
• shadcn/ui initialized (npx shadcn@latest init)

Available Components

Component APIs

Each section uses the same outline: Import → Parts → Root props → Props & hooks → Usage notes → Example (when a short snippet helps).

Prompt Input

Composable chat shell: auto-growing textarea plus a bottom action row for attach/send and similar controls.

Import:

import {
  PromptInput,
  PromptInputTextarea,
  PromptInputActions,
  PromptInputActionGroup,
  PromptInputAction,
} from "@/components/nexus-ui/prompt-input";

Parts:

Root props: Optional onSubmit(value: string) on PromptInput for Enter-to-submit from PromptInputTextarea (Shift+Enter adds newline), plus normal DOM attributes / className.

Props & hooks: Every part accepts className. PromptInputTextarea accepts standard textarea props. PromptInputAction supports asChild and tooltip?: string | { content?: string; side?: "top" | "right" | "bottom" | "left"; shortcut?: string } (no tooltip renders when content is missing). There is no context hook.

Usage notes: Put attach/tools in the first PromptInputActionGroup and send in the second so justify-between separates them. Prefer PromptInputAction asChild around Button rather than using PromptInputAction as the clickable element itself.

Example:

<PromptInput>
  <PromptInputTextarea placeholder="Ask anything..." />
  <PromptInputActions>
    <PromptInputActionGroup>
      <PromptInputAction asChild>
        <Button variant="ghost" size="icon" className="rounded-full">
          <Paperclip />
        </Button>
      </PromptInputAction>
    </PromptInputActionGroup>
    <PromptInputActionGroup>
      <PromptInputAction asChild>
        <Button size="icon" className="rounded-full">
          <ArrowUp />
        </Button>
      </PromptInputAction>
    </PromptInputActionGroup>
  </PromptInputActions>
</PromptInput>

Model Selector

Dropdown for picking a model (or similar value), built on Radix DropdownMenu with optional items metadata for labels, descriptions, and icons.

Import:

import {
  ModelSelector,
  ModelSelectorPortal,
  ModelSelectorTrigger,
  ModelSelectorContent,
  ModelSelectorGroup,
  ModelSelectorLabel,
  ModelSelectorItemTitle,
  ModelSelectorItemDescription,
  ModelSelectorItemIcon,
  ModelSelectorItemIndicator,
  ModelSelectorItem,
  ModelSelectorCheckboxItem,
  ModelSelectorRadioGroup,
  ModelSelectorRadioItem,
  ModelSelectorSeparator,
  ModelSelectorSub,
  ModelSelectorSubTrigger,
  ModelSelectorSubContent,
} from "@/components/nexus-ui/model-selector";

Parts:

Root props: On ModelSelector, value and onValueChange are required. Optional items: { value, title, description?, icon? }[] to populate trigger copy and internal metadata. Other Radix menu-root props apply, but value / onValueChange on the root are reserved for this API.

Props & hooks: ModelSelectorTrigger adds variant: filled | outline | ghost (default filled). Selection state lives in your React state (value / onValueChange); there is no extra hook beyond Radix behavior.

Usage notes: Prefer ModelSelectorRadioGroup + ModelSelectorRadioItem for exclusive choices; use ModelSelectorCheckboxItem when multiple toggles are needed. Nest advanced trees with ModelSelectorSub / SubTrigger / SubContent. Long menus benefit from ModelSelectorGroup, ModelSelectorLabel, and ModelSelectorSeparator.

Example:

// models: { value: string; title: string; description?: string; icon?: ComponentType<{ className?: string }> }[]
const [model, setModel] = React.useState(models[0].value);

<ModelSelector value={model} onValueChange={setModel} items={models}>
  <ModelSelectorTrigger />
  <ModelSelectorContent align="start">
    <ModelSelectorGroup>
      <ModelSelectorLabel>Select model</ModelSelectorLabel>
      <ModelSelectorRadioGroup value={model} onValueChange={setModel}>
        {models.map((m) => (
          <ModelSelectorRadioItem
            key={m.value}
            value={m.value}
            icon={m.icon}
            title={m.title}
            description={m.description}
          />
        ))}
      </ModelSelectorRadioGroup>
    </ModelSelectorGroup>
  </ModelSelectorContent>
</ModelSelector>

Suggestions

Chips for quick prompts, with an optional animated panel for grouped suggestions.

Import:

import Suggestions, {
  SuggestionList,
  Suggestion,
  SuggestionPanel,
  SuggestionPanelHeader,
  SuggestionPanelTitle,
  SuggestionPanelClose,
  SuggestionPanelContent,
} from "@/components/nexus-ui/suggestions";

Parts:

Root props: Suggestions — optional onSelect(value: string). SuggestionPanel — optional open (default true), onOpenChange, onClose (runs after the exit animation).

Props & hooks: No selector hook; wire behavior through onSelect and Suggestion’s Button props. Suggestion omits outer variant in favor of the Nexus variant union above.

Usage notes: Combine multiple SuggestionList blocks or place lists inside SuggestionPanel for progressive disclosure. highlight dims matching substrings inside chip labels. Use SuggestionPanelClose in the header for dismiss affordances.

Example:

// Often paired with prompt state: onSelect((q) => setInput(q))
<Suggestions onSelect={(q) => setInput(q)}>
  <SuggestionList>
    <Suggestion value="Summarize this thread">Summarize this thread</Suggestion>
    <Suggestion value="Draft a reply">Draft a reply</Suggestion>
  </SuggestionList>
</Suggestions>

Attachments

Controlled file previews for a prompt or message row: hidden file input, optional window-level drag/drop, and per-item remove/progress UI.

Import:

import Attachments, {
  AttachmentTrigger,
  AttachmentList,
  Attachment,
  AttachmentPreview,
  AttachmentRemove,
  AttachmentInfo,
  AttachmentProperty,
  AttachmentProgress,
  AttachmentsDropOverlay,
  useAttachments,
  toAttachmentMeta,
  filesFromDataTransfer,
} from "@/components/nexus-ui/attachments";

Parts:

Root props: On Attachments, required attachments and onAttachmentsChange. Optional: accept, multiple (default true), maxFiles, maxSize (per file, bytes), disabled, onFileInputChange, onFilesRejected, windowDrop.

Props & hooks: useAttachments() — only under <Attachments> — exposes inputRef, inputId, openPicker, appendFiles, isDraggingFile, current attachments, onAttachmentsChange, limits, and disabled. Exported types: AttachmentMeta, AttachmentsRejectedFiles, AppendFilesOptions. Helpers: toAttachmentMeta(file, options?), filesFromDataTransfer for paste/drop.

Usage notes: Call appendFiles from custom drop/paste handlers to reuse the same limits as the native picker. Enable windowDrop plus AttachmentsDropOverlay for app-wide file drag hints. Object URLs are revoked when items disappear from the controlled attachments array.

Example:

const [items, setItems] = React.useState<AttachmentMeta[]>([]);

<Attachments attachments={items} onAttachmentsChange={setItems} accept="image/*" maxFiles={5}>
  <AttachmentTrigger />
  <AttachmentList>
    {items.map((meta, index) => (
      <Attachment
        key={meta.url ?? `${meta.name}-${index}`}
        attachment={meta}
        variant="compact"
        onRemove={() => setItems(items.filter((_, i) => i !== index))}
      />
    ))}
  </AttachmentList>
</Attachments>

Message

User vs assistant rows with optional avatar, markdown body (via Streamdown), and trailing actions.

Import:

import {
  Message,
  MessageStack,
  MessageContent,
  MessageMarkdown,
  MessageActions,
  MessageActionGroup,
  MessageAction,
  MessageAvatar,
} from "@/components/nexus-ui/message";

Parts:

Root props: On Message, required from: "user" | "assistant". Standard HTMLAttributes<HTMLDivElement> apply to the article wrapper. Default aria-label is "User message" or "Assistant message" unless you pass aria-label or aria-labelledby.

Props & hooks: No exported context hook. Descendants (MessageStack, MessageContent, MessageActions, etc.) read from from internal context (fallback assistant if used outside Message). MessageMarkdown accepts Streamdown props (ComponentProps<typeof Streamdown>): e.g. markdown via children, optional components merged over built-in code / table / inlineCode defaults, plus className. MessageAction supports asChild (Radix Slot) and tooltip?: string | { content?: string; side?: "top" | "right" | "bottom" | "left"; shortcut?: string } (no tooltip renders when content is missing). MessageAvatar: required src; optional alt, fallback, delayMs, size, className.

Usage notes: Registry install adds codeblock.tsx next to message.tsx. Merge Streamdown-related CSS from the registry item when installing manually. Prefer MessageAction asChild around Button for actions.

Example:

<Message from="assistant">
  <MessageAvatar src="https://github.com/shadcn.png" fallback="AI" />
  <MessageStack>
    <MessageContent>
      <MessageMarkdown>Here is **markdown** and `inline code`.</MessageMarkdown>
    </MessageContent>
    <MessageActions>
      <MessageActionGroup>
        <MessageAction asChild>
          <Button type="button" variant="ghost" size="sm">
            Copy
          </Button>
        </MessageAction>
      </MessageActionGroup>
    </MessageActions>
  </MessageStack>
</Message>

<Message from="user">
  <MessageContent>
    <MessageMarkdown>Short user reply</MessageMarkdown>
  </MessageContent>
</Message>

Thread

Wraps use-stick-to-bottom for a scrollable message list that stays pinned to new content, with a floating control when the user scrolls up.

Import:

import {
  Thread,
  ThreadContent,
  ThreadScrollToBottom,
} from "@/components/nexus-ui/thread";

Parts:

Root props: Thread is StickToBottom with defaults resize="smooth" and initial="smooth". Optional StickToBottomOptions: resize, initial, mass, damping, stiffness, targetScrollTop. Also instance (pre-created stick-to-bottom instance), contextRef, and normal HTMLAttributes on the outer div.

Props & hooks: Inside Thread, use useStickToBottomContext() from use-stick-to-bottom for isAtBottom, scrollToBottom, state, etc. ThreadScrollToBottom uses that context internally and returns null when already at the bottom. It accepts asChild plus standard button HTML attributes (when not asChild, renders a styled <button>).

Usage notes: Place ThreadContent and ThreadScrollToBottom as siblings inside Thread. Give Thread a bounded height (e.g. h-full / min-h-*) so the scroll region is defined.

Example:

<Thread className="min-h-[480px]">
  <ThreadContent>
    {messages.map((m) => (
      <Message key={m.id} from={m.role === "user" ? "user" : "assistant"}>
        <MessageContent>
          <MessageMarkdown>{m.text}</MessageMarkdown>
        </MessageContent>
      </Message>
    ))}
  </ThreadContent>
  <ThreadScrollToBottom />
</Thread>

Citation

Composable inline citation chip(s) with Radix HoverCard preview. Multiple URLs use a carousel inside the panel (CitationCarousel*).

Import:

import {
  Citation,
  CitationTrigger,
  CitationContent,
  CitationSource,
  CitationSourcesBadge,
  CitationItem,
  CitationFavicon,
  CitationSiteName,
  CitationCarousel,
  CitationCarouselContent,
  CitationCarouselHeader,
  CitationCarouselItem,
  CitationCarouselPrev,
  CitationCarouselNext,
  CitationCarouselPagination,
  CitationCarouselIndex,
} from "@/components/nexus-ui/citation";

Helpers: resolveCitationSources, resolveCitationSource, parseCitationUrl, rootDomainSiteName, types CitationSourceInput, ResolvedCitation.

Parts:

Root props: On Citation, required citations: CitationSourceInput[] (url, optional title, description). All other props omit children from HoverCard and pass through; optional children compose trigger + content. Renders null if citations is empty. openDelay / closeDelay are set to 50 on the root card.

Props & hooks: No exported hooks; CitationItem, CitationFavicon, etc. require an ancestor Citation and (for items inside the carousel) a matching CitationCarouselItem with index. CitationTrigger: optional label, showFavicon (default true), showSiteName (default true). CitationCarouselItem: required index: number. CitationItem: optional showTitle, showDescription, showSource (defaults true); href defaults to resolved URL. CitationSourcesBadge: optional showFavicons, label.

Usage notes: Build citations from your RAG / search pipeline; use resolveCitationSources if you normalize URLs yourself. For two or more URLs, put CitationCarousel + one CitationCarouselItem per index inside CitationContent. CitationSourcesBadge is optional chrome for message headers or actions, still under Citation.

Example (single source):

<Citation
  citations={[
    {
      url: "https://vercel.com/blog",
      title: "Vercel Blog",
      description: "Product and platform updates.",
    },
  ]}
>
  <CitationTrigger />
  <CitationContent>
    <CitationItem />
  </CitationContent>
</Citation>

Example (multiple sources + carousel):

const sources = [
  { url: "https://example.com/a", title: "Source A" },
  { url: "https://example.com/b", title: "Source B" },
];

<Citation citations={sources}>
  <CitationTrigger />
  <CitationContent>
    <CitationCarousel>
      <CitationCarouselHeader>
        <CitationSourcesBadge />
        <CitationCarouselPagination>
          <CitationCarouselPrev />
          <CitationCarouselIndex />
          <CitationCarouselNext />
        </CitationCarouselPagination>
      </CitationCarouselHeader>
      <CitationCarouselContent>
        {sources.map((_, index) => (
          <CitationCarouselItem key={index} index={index}>
            <CitationItem />
          </CitationCarouselItem>
        ))}
      </CitationCarouselContent>
    </CitationCarousel>
  </CitationContent>
</Citation>

Reasoning

Collapsible “thinking” block built on shadcn Collapsible: the trigger label shifts from streaming copy to a duration summary, and the body renders markdown via Streamdown.

Import:

import {
  Reasoning,
  ReasoningTrigger,
  ReasoningContent,
} from "@/components/nexus-ui/reasoning";

Parts:

Root props: On Reasoning, optional isStreaming (default false) drives auto-open while streaming and auto-close plus duration bookkeeping when streaming ends; optional controlled open / defaultOpen / onOpenChange (inherits from collapsible semantics but Reasoning omits Radix open/defaultOpen/onOpenChange from its type in favor of the listed props). Accepts remaining Collapsible-compatible props plus className.

Props & hooks: No exported hook (internal context only). ReasoningTrigger/ReasoningContent must be descendants of Reasoning. Registry install pulls collapsible, streamdown, Hugeicons packages, @import "tw-shimmer", and keyframes for collapsible height animation.

Usage notes: Toggle isStreaming from your chat transport / part stream. Omit ReasoningTrigger children to use the computed label; pass children only when you override the visible label while keeping accessibility in mind.

Example:

<Reasoning isStreaming={status === "streaming"}>
  <ReasoningTrigger />
  <ReasoningContent>{reasoningMarkdownString}</ReasoningContent>
</Reasoning>

Text Shimmer

Single primitive that animates a moving highlight across text (bg-clip-text + injected @keyframes). No extra UI dependencies beyond @/lib/utils.

Import:

import { TextShimmer } from "@/components/nexus-ui/text-shimmer";

Parts: Single component — TextShimmer. Optional polymorphic root via as (default "span").

Root props: duration — active sweep duration in seconds (default 2.5); repeatDelay — pause before the next sweep (default 0); spread — highlight width in percentage points around center, clamped ~5–45 (default 20); angle — degrees added to the gradient axis (default 0); color — override beam stop color; invert — flip default light/dark beam contrast; plus standard HTML attributes/className/style. Children are the label text/node tree.

Props & hooks: No context. Injects a unique @keyframes name per instance via useId.

Usage notes: Prefer on short status strings (“Running tools…”). Combine with muted text-muted-foreground on the wrapper if the edge color should inherit from typography.

Example:

<TextShimmer repeatDelay={0.5}>Running tool calls</TextShimmer>