Sources

npx shadcn@latest add "@assistant-ui/sources"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-sources"

Sources renders one citation from a message: a url source as a small link with a favicon and title, or a document source as a badge with a document icon. With a runtime it renders straight from a message's source part; standalone you hand it the part yourself. It comes in two designs: the runtime variant renders an inline link or badge next to the message text, and the static source-cards variant collapses every citation into one pill that expands into a grid of scannable cards (see The source-cards design).

Getting started

import { Sources } from "@/components/assistant-ui/elements/sources.aui";
import { MessagePrimitive } from "@assistant-ui/react";

function AssistantMessage() {
  return (
    <MessagePrimitive.Root>
      <MessagePrimitive.Parts components={{ Source: Sources }} />
    </MessagePrimitive.Root>
  );
}

import { Sources } from "@/components/assistant-ui/elements/sources.aui";

export function Citation() {
  return (
    <Sources
      type="source"
      sourceType="url"
      id="src-1"
      url="https://example.com/article"
      title="Example Article"
      status={{ type: "complete" }}
    />
  );
}

Anatomy

{/* sourceType: "url" */}
<a data-slot="source" href={url}>
  <img data-slot="source-icon" />
  <span data-slot="source-title">{title ?? domain}</span>
</a>

{/* sourceType: "document" */}
<span data-slot="source">
  <span data-slot="source-document-icon" />
  <span data-slot="source-title">{title}</span>
</span>

The favicon requests https://icons.duckduckgo.com/ip3/<domain>.ico by default; when that image fails to load, the icon falls back to a single letter drawn from the domain. The link's visible title is title when the source provides one, otherwise the bare domain with www. stripped. A document source never links anywhere and always shows its title. A url source with an empty url, or any other sourceType, renders nothing.

Examples

Custom favicon and variant

Sources itself takes only the part; to override the favicon lookup or restyle the link, compose the exported sub-parts into your own renderer and register that instead:

import { Sources } from "@/components/assistant-ui/elements/sources.aui";
import type { ComponentProps } from "react";

function CustomSource(part: ComponentProps<typeof Sources>) {
  if (part.sourceType !== "url" || !part.url) return null;
  return (
    <Sources.Root href={part.url} variant="secondary">
      <Sources.Icon
        url={part.url}
        faviconUrl={(domain) => `https://logo.clearbit.com/${domain}`}
      />
      <Sources.Title>{part.title}</Sources.Title>
    </Sources.Root>
  );
}

Use CustomSource in place of Sources in MessagePrimitive.Parts, or call it directly with a hand-built part.

Favicon fallback

When the favicon fails to load, Sources.Icon falls back to the domain's first letter. The demo points faviconUrl at a path that does not resolve:

PreviewCode

Example Reference

Variants and sizes

Sources.Root carries the styling. Pass variant and size when you compose your own renderer as above. The Variants demo in the rail shows each variant.

API reference

The source-cards design

The Static variant in the rail is a second design for the same citations: instead of an inline link or badge next to the message text, it collapses every citation into one pill that expands into a grid of cards, each with a domain avatar, the domain, and the title. It is a single props-driven component with no runtime dependency:

npx shadcn@latest add "@assistant-ui/elements-sources"

"use client";

import { useMemo, useState } from "react";
import { useAuiState } from "@assistant-ui/react";
import { Sources, type Source } from "@/components/assistant-ui/elements/sources";

function extractDomain(url: string) {
  try {
    return new URL(url).hostname.replace(/^www\./, "");
  } catch {
    return url;
  }
}

export function MessageSources() {
  const parts = useAuiState((s) => s.message.parts);
  const [open, setOpen] = useState(false);

  const sources = useMemo<Source[]>(
    () =>
      parts.flatMap((part) => {
        if (part.type !== "source" || part.sourceType !== "url") return [];
        const domain = extractDomain(part.url);
        return [{ domain, title: part.title ?? domain }];
      }),
    [parts],
  );

  if (sources.length === 0) return null;
  return <Sources sources={sources} open={open} onOpenChange={setOpen} />;
}

"use client";

import { useState } from "react";
import { Sources, type Source } from "@/components/assistant-ui/elements/sources";

const SOURCES: Source[] = [
  { domain: "assistant-ui.com", title: "Runtime drafts API" },
  { domain: "react.dev", title: "You might not need an effect" },
];

export function Citations() {
  const [open, setOpen] = useState(false);
  return <Sources sources={SOURCES} open={open} onOpenChange={setOpen} />;
}

Nothing inside the element opens or closes the panel: open and onOpenChange do. The trigger's count always reads sources.length, whether the panel is open or not; an empty sources array leaves the trigger reading "0" and the panel opens onto an empty grid.

The Sources component

Source is { domain: string; title: string }. Unlike most elements in this catalog, this Sources does not spread extra props onto its root: only the four props above reach it.