---
title: Citation
description: Inline source references with hover preview
---

import CitationDefault from "@/components/nexus-ui/examples/citation/default";
import CitationMultipleSources from "@/components/nexus-ui/examples/citation/multiple-sources";
import CitationTriggerVariants from "@/components/nexus-ui/examples/citation/trigger-variants";
import CitationInlineWithText from "@/components/nexus-ui/examples/citation/inline-with-text";

Inline chip for showing a **source reference** with **hover preview** (favicon, label, and card copy for title, description, and link). Pass **`citations`** as an array of **`{ url, title?, description? }`**—**one entry** gives a single citation; **several entries** pair with **`CitationCarousel`** and **`CitationCarouselItem`** so users can move between sources in the same preview.

<DemoWithCode src="components/nexus-ui/examples/citation/default.tsx">
  <CitationDefault />
</DemoWithCode>

## Installation

<Tabs items={["CLI", "Manual"]} framed={false}>
<Tab value="CLI">
<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
<Tab value="npm">
```bash
npx shadcn@latest add @nexus-ui/citation
```
</Tab>
<Tab value="pnpm">
```bash
pnpm dlx shadcn@latest add @nexus-ui/citation
```
</Tab>
<Tab value="yarn">
```bash
yarn dlx shadcn@latest add @nexus-ui/citation
```
</Tab>
<Tab value="bun">
```bash
bunx shadcn@latest add @nexus-ui/citation
```
</Tab>
</Tabs>
</Tab>
<Tab value="Manual">
<Steps>
<Step>
<h3>Copy and paste the following code into your project.</h3>

<ComponentSource src="registry/new-york/citation/citation.tsx" title="components/nexus-ui/citation.tsx" />
</Step>
<Step>
<h3>Install registry dependencies: <code>@nexus-ui/nexus-ui-theme</code>, <code>carousel</code>, and <code>hover-card</code> (or use the CLI so they install automatically).</h3>
</Step>
<Step>
<h3>Update the import paths to match your project setup.</h3>
</Step>
</Steps>
</Tab>
</Tabs>

## Usage

```tsx keepBackground noCollapse
import {
  Citation,
  CitationContent,
  CitationItem,
  CitationTrigger,
} from "@/components/nexus-ui/citation";
```

```tsx keepBackground noCollapse
<Citation citations={[{ url: "https://example.com", title: "Example", description: "…" }]}>
  <CitationTrigger />
  <CitationContent>
    <CitationItem />
  </CitationContent>
</Citation>
```

`CitationItem` renders a default **`h4`** title, **`p`** description, and **`CitationSource`** footer. Toggle blocks with **`showTitle`**, **`showDescription`**, and **`showSource`**, or pass **`children`** to replace the default layout entirely (e.g. custom order or **`CitationSource`** only).

## Examples

### Multiple sources

With more than one **`citations`** entry, the default chip shows **`+N`** after the first source. **`CitationCarousel`** wraps a shadcn **`Carousel`** component inside the hover card so each source is one slide—users move between them with prev/next (or swipe) without closing the preview.

<DemoWithCode src="components/nexus-ui/examples/citation/multiple-sources.tsx">
  <CitationMultipleSources />
</DemoWithCode>

### Trigger label and favicon

The built-in **`CitationTrigger`** chip can be adjusted with **`showFavicon`** and **`showSiteName`**. Use **`label`** to replace the auto-derived site name with any string—numbers, hostname, or text from **`resolveCitationSource`** / **`parseCitationUrl`** when you want it derived in code.

<DemoWithCode src="components/nexus-ui/examples/citation/trigger-variants.tsx">
  <CitationTriggerVariants />
</DemoWithCode>

### Inline with text

The trigger can sit **inline** with surrounding copy—place **`Citation`** where a phrase or sentence needs a source chip.

<DemoWithCode src="components/nexus-ui/examples/citation/inline-with-text.tsx">
  <CitationInlineWithText />
</DemoWithCode>

## Vercel AI SDK Integration

The [Vercel AI SDK](https://sdk.vercel.ai) does not define a single standard for **inline citations** in chat streams—models are not required to emit a shared citation syntax, and there is no built-in “citation” channel you can rely on for every provider. [Streamdown](https://streamdown.ai/) also has **no official inline-citation or footnote-to-chip resolution**; you have to wire sources yourself.

**Citation** takes **`citations: CitationSourceInput[]`** only. In practice, you can fill that array from **(1)** a **structured object** stream (**`streamObject`** + **`experimental_useObject`**) with a Zod schema, or **(2)** assistant **`UIMessage`** parts of **`type: "source-url"`** from **`useChat`** when your **`POST /api/chat`** response actually includes them (**`toUIMessageStreamResponse({ sendSources: true })`** and a model or provider that emits source parts—many completions only stream **`text`**).

### Structured object stream

<Steps>
<Step>
<h3>Install the AI SDK and Zod</h3>

```bash
npm install ai @ai-sdk/react @ai-sdk/openai zod
```

</Step>
<Step>
<h3>Add the citation API route</h3>

Define the Zod schema in this file and export it so the client can pass the same shape to **`useObject`**.

```ts title="app/api/citation/route.ts"
import { streamObject, zodSchema } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

export const citationSchema = z.object({
  content: z.string(),
  citations: z.array(
    z.object({
      number: z.string(),
      title: z.string(),
      url: z.string(),
      description: z.string().optional(),
    }),
  ),
});

export const maxDuration = 30;

export async function POST(req: Request) {
  const { prompt } = (await req.json()) as { prompt: string };

  const result = streamObject({
    model: openai("gpt-4o"),
    schema: zodSchema(citationSchema),
    prompt: `Generate a well-researched paragraph about ${prompt} with proper citations.

Include:
- A comprehensive paragraph with inline citations marked as [1], [2], etc.
- 2-3 citations with realistic source information
- Each citation should have a title, URL, and optional description
- Make the content informative and the sources credible

Format citations as numbered references within the text.`,
  });

  return result.toTextStreamResponse();
}
```

</Step>
<Step>
<h3>Add a client page for structured citations</h3>

```tsx title="app/citations-object/page.tsx"
"use client";

import { experimental_useObject as useObject } from "@ai-sdk/react";
import { Button } from "@/components/ui/button";
import {
  Citation,
  CitationContent,
  CitationItem,
  CitationTrigger,
} from "@/components/nexus-ui/citation";
import { citationSchema } from "@/app/api/citation/route";

export default function CitationsObjectPage() {
  const { object, submit, isLoading } = useObject({
    api: "/api/citation",
    schema: citationSchema,
  });

  return (
    <div className="mx-auto max-w-4xl space-y-6 p-6">
      <div className="flex flex-wrap gap-2">
        <Button
          type="button"
          onClick={() => submit({ prompt: "how tidal power works" })}
          disabled={isLoading}
          variant="outline"
        >
          Tidal energy
        </Button>
        <Button
          type="button"
          onClick={() =>
            submit({ prompt: "the history of the printing press in Europe" })
          }
          disabled={isLoading}
          variant="outline"
        >
          Printing history
        </Button>
      </div>

      {isLoading && !object ? (
        <p className="text-muted-foreground text-sm">
          Generating content with citations…
        </p>
      ) : null}

      {object?.content ? (
        <div className="prose prose-sm max-w-none">
          <p className="leading-relaxed">
            {object.content.split(/(\[\d+\])/).map((part, index) => {
              const citationMatch = part.match(/\[(\d+)\]/);
              if (citationMatch) {
                const citationNumber = citationMatch[1];
                const row = object.citations?.find(
                  (c) => c.number === citationNumber,
                );
                if (row) {
                  return (
                    <Citation
                      key={index}
                      citations={[
                        {
                          url: row.url,
                          title: row.title,
                          description: row.description,
                        },
                      ]}
                    >
                      <CitationTrigger />
                      <CitationContent>
                        <CitationItem />
                      </CitationContent>
                    </Citation>
                  );
                }
              }
              return part;
            })}
          </p>
        </div>
      ) : null}
    </div>
  );
}
```

</Step>
</Steps>

### Chat stream with source-url parts

<Steps>
<Step>
<h3>Install the AI SDK</h3>

```bash
npm install ai @ai-sdk/react @ai-sdk/openai
```

</Step>
<Step>
<h3>Add the chat API route</h3>

```ts title="app/api/chat/route.ts"
import { convertToModelMessages, streamText, type UIMessage } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: openai("gpt-4o-mini"),
    system:
      "You are a helpful assistant. When you cite web sources, include URLs in your answer where applicable.",
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse({
    sendSources: true,
  });
}
```

</Step>
<Step>
<h3>Add a client page for chat citations</h3>

```tsx title="app/citations-chat/page.tsx"
"use client";

import { useCallback, useMemo, useState } from "react";
import { useChat } from "@ai-sdk/react";
import {
  DefaultChatTransport,
  isTextUIPart,
  type UIMessage,
} from "ai";
import { Button } from "@/components/ui/button";
import {
  Citation,
  CitationContent,
  CitationItem,
  CitationTrigger,
  type CitationSourceInput,
} from "@/components/nexus-ui/citation";

function textFromMessage(message: UIMessage) {
  return message.parts.filter(isTextUIPart).map((p) => p.text).join("");
}

function citationsFromSourceUrlParts(
  message: UIMessage,
): CitationSourceInput[] {
  return message.parts
    .filter(
      (p): p is Extract<UIMessage["parts"][number], { type: "source-url" }> =>
        p.type === "source-url",
    )
    .map((p) => ({
      url: p.url,
      title: p.title,
    }));
}

export default function CitationsChatPage() {
  const [input, setInput] = useState("");
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({ api: "/api/chat" }),
  });

  const lastAssistant = useMemo(
    () => [...messages].reverse().find((m) => m.role === "assistant"),
    [messages],
  );

  const citations = lastAssistant
    ? citationsFromSourceUrlParts(lastAssistant)
    : [];
  const assistantText = lastAssistant ? textFromMessage(lastAssistant) : "";
  const isBusy = status === "submitted" || status === "streaming";

  const handleSubmit = useCallback(() => {
    const t = input.trim();
    if (!t) return;
    sendMessage({ text: t });
    setInput("");
  }, [input, sendMessage]);

  return (
    <div className="mx-auto flex max-w-xl flex-col gap-4 p-6">
      <textarea
        value={input}
        onChange={(e) => setInput(e.target.value)}
        className="min-h-[80px] w-full rounded-md border border-border bg-background p-2 text-sm"
        placeholder="Ask something…"
      />
      <Button type="button" onClick={handleSubmit} disabled={isBusy}>
        Send
      </Button>
      {assistantText ? (
        <p className="text-sm leading-relaxed">{assistantText}</p>
      ) : null}
      {citations.length > 0 ? (
        <Citation citations={citations}>
          <CitationTrigger />
          <CitationContent>
            <CitationItem />
          </CitationContent>
        </Citation>
      ) : null}
    </div>
  );
}
```

</Step>
</Steps>

## API Reference

### Citation

Root component. **Normalizes** **`citations`**, stores **citation source data** and **carousel** state in context for descendants, and wraps **[Hover Card](https://www.radix-ui.com/primitives/docs/components/hover-card#root)**.

<TypeTable
  type={{
    defaultOpen: {
      type: "boolean",
      description: "Uncontrolled initial open state.",
    },
    open: {
      type: "boolean",
      description: "Controlled open state.",
    },
    onOpenChange: {
      type: "(open: boolean) => void",
      description: "Called when the open state changes.",
    },
    openDelay: {
      type: "number",
      description:
        "The duration from when the mouse enters the trigger or content until the hover card opens.",
      default: "50ms",
    },
    closeDelay: {
      type: "number",
      description:
        "The duration from when the mouse leaves the trigger or content until the hover card closes.",
      default: "50ms",
    },
    citations: {
      type: "CitationSourceInput[]",
      description:
        "Source(s) to show. Each item requires url; title and description are optional for the preview.",
    },
    children: {
      type: "React.ReactNode",
      description:
        "Typically CitationTrigger and CitationContent (and carousel or item primitives inside the content).",
    },
  }}
/>

### CitationTrigger

The **source chip** users see in the UI. Wraps **[Hover Card Trigger](https://www.radix-ui.com/primitives/docs/components/hover-card#trigger)** so hovering it opens the **preview** (`CitationContent`). Adjust the chip with **`label`**, **`showFavicon`**, and **`showSiteName`**.

<TypeTable
  type={{
    label: {
      type: "React.ReactNode",
      description:
        "Replaces the auto-derived site-name text on the default chip.",
    },
    showFavicon: {
      type: "boolean",
      default: "true",
      description: "Show the first source’s favicon on the default chip.",
    },
    showSiteName: {
      type: "boolean",
      default: "true",
      description:
        "Show site-name (or label) text. When false with favicon on, yields a favicon-only chip.",
    },
    className: {
      type: "string",
      description: "Merged with default chip styles.",
    },
  }}
/>

### CitationContent

Preview card that appears when the trigger is hovered and shows the source details; Wraps **[Hover Card Content](https://www.radix-ui.com/primitives/docs/components/hover-card#content)**.

<TypeTable
  type={{
    align: {
      type: '"start" | "center" | "end"',
      default: '"center"',
      description: "Alignment relative to the trigger.",
    },
    alignOffset: {
      type: "number",
      default: "0",
      description: "Pixel offset along the alignment axis.",
    },
    side: {
      type: '"top" | "right" | "bottom" | "left"',
      default: '"bottom"',
      description: "Preferred side of the trigger for the popover.",
    },
    sideOffset: {
      type: "number",
      default: "4",
      description: "Distance from the trigger in px.",
    },
    className: {
      type: "string",
      description: "Merged with default card shell styles.",
    },
  }}
/>

### CitationCarousel

[**Carousel**](https://ui.shadcn.com/docs/components/radix/carousel) root for multi-source slides. **`setApi`** registers the API on **`Citation`** (for nav/index) and invokes any **`setApi`** you pass.

<TypeTable
  type={{
    orientation: {
      type: '"horizontal" | "vertical"',
      default: '"horizontal"',
      description:
        "Carousel axis; forwarded to Embla via the shared Carousel primitive.",
    },
    opts: {
      type: "object",
      description: "Optional Embla carousel options.",
    },
    plugins: {
      type: "EmblaPlugin | EmblaPlugin[]",
      description: "Optional Embla plugins array.",
    },
    setApi: {
      type: "(api: CarouselApi | undefined) => void",
      description:
        "Optional; invoked when the Embla instance is ready or cleared.",
    },
    className: {
      type: "string",
      description: "Classes on the carousel region wrapper.",
    },
  }}
/>

### CitationCarouselHeader

Header row above the slide viewport; Usually contains a summary **`CitationSource`** and **`CitationCarouselPagination`**.

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Default includes horizontal padding and top padding.",
    },
  }}
/>

### CitationCarouselContent

Wraps **[Carousel Content](https://ui.shadcn.com/docs/components/radix/carousel#content)** and syncs viewport **height** to the **active** slide.

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Classes on the flex track inside the overflow viewport.",
    },
  }}
/>

### CitationCarouselItem

One carousel slide; **`index`** selects **`citations[index]`** and sets **`CitationItemContext`**. Wraps **[Carousel Item](https://ui.shadcn.com/docs/components/radix/carousel#item)**.

<TypeTable
  type={{
    index: {
      type: "number",
      description: "Zero-based index into Citation citations.",
    },
    className: {
      type: "string",
      description: "Merged with slide layout (includes self-start).",
    },
  }}
/>

### CitationCarouselPagination

Flex row for nav controls.

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Default flex row with gap for prev / index / next.",
    },
  }}
/>

### CitationCarouselPrev / CitationCarouselNext

Icon buttons for prev/next navigation; Standard **`button`** HTML attributes.

<TypeTable
  type={{
    children: {
      type: "React.ReactNode",
      description: "Replace the default Hugeicons arrows.",
    },
    className: {
      type: "string",
      description: "Merged with default circular button styles.",
    },
  }}
/>

### CitationCarouselIndex

**`current / count`** from context (**1-based** current). **`span`** HTML attributes.

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Default tabular-nums muted text.",
    },
  }}
/>

### CitationItem

Preview row as an **`<a>`**, containing the source details; **`href`** defaults to the citation URL. Default stack: **`h4`** title, **`p`** description, **`CitationSource`** footer.

<TypeTable
  type={{
    showTitle: {
      type: "boolean",
      default: "true",
      description: "Show the title block.",
    },
    showDescription: {
      type: "boolean",
      default: "true",
      description: "Show the description block.",
    },
    showSource: {
      type: "boolean",
      default: "true",
      description: "Show the footer source row.",
    },
    href: {
      type: "string",
      description: "Active or item-scoped citation url.",
    },
    className: {
      type: "string",
      description: "Default column layout with padding inside the hover card.",
    },
    children: {
      type: "React.ReactNode",
      description:
        "Replaces the default title, description, and source stack when set.",
    },
  }}
/>

### CitationSource

Citation source chip with the favicon and site name.

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Merged with default flex row with gap.",
    },
  }}
/>

### CitationFavicon

Favicon of the citation site. **`src`** overrides **`faviconSrc`** from context.

<TypeTable
  type={{
    src: {
      type: "string",
      description: "Optional favicon URL; defaults from citation context.",
    },
    className: {
      type: "string",
      description: "Wrapper div classes (size defaults to icon scale).",
    },
  }}
/>

### CitationSiteName

Site name of the citation site.

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Merged with default truncate text-primary.",
    },
  }}
/>

### CitationSourcesBadge

Chip with an optional overlapping favicon stack plus a **`{n} source(s)`** label. Use in **`CitationCarouselHeader`**, message action rows, or anywhere inside **`Citation`**.

<TypeTable
  type={{
    showFavicons: {
      type: "boolean",
      default: "true",
      description: "Show the stacked favicons before the label.",
    },
    label: {
      type: "React.ReactNode",
      description: "Optional; defaults to “N source(s)” from citation count.",
    },
    className: {
      type: "string",
      description: "Secondary rounded-full row; tight padding for the chip.",
    },
  }}
/>

### parseCitationUrl

Tolerant parse to a **`URL`**: trims the string and, when no **`http`/`https`** scheme is present, prefixes **`https://`** so bare hostnames resolve. Use for hostname extraction, favicon lookups, or custom **`CitationTrigger`** labels outside the component tree.

```ts
export function parseCitationUrl(urlStr: string): URL;
```

### resolveCitationSource

Maps one **`CitationSourceInput`** to **`ResolvedCitation`**—normalized **`url`**, optional **`title`** / **`description`**, derived **`siteName`**, and a **`faviconSrc`** URL. **`resolveCitationSources`** maps an array; **`Citation`** uses this pipeline when resolving the **`citations`** prop.

```ts noCollapse
export type CitationSourceInput = {
  url: string;
  title?: React.ReactNode;
  description?: React.ReactNode;
};

export type ResolvedCitation = {
  url: string;
  title: React.ReactNode | null;
  description: React.ReactNode | null;
  siteName: string;
  faviconSrc: string;
};

export function resolveCitationSource(
  input: CitationSourceInput,
): ResolvedCitation;

export function resolveCitationSources(
  inputs: CitationSourceInput[],
): ResolvedCitation[];
```