# Citation

A numbered marker in a reply that links to a source and previews it on hover.

Source: [citation.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/citation.tsx)

```tsx
"use client";

import { GlobeIcon } from "lucide-react";

import {
  Citation,
  CitationContent,
  CitationDescription,
  CitationSource,
  CitationTitle,
  CitationTrigger,
} from "@/components/ui/citation";
import { preventNavigation } from "@/examples/data";

const sources = [
  {
    site: "example.com",
    title: "Custom domains",
    description: "Add a domain, then point it at your site with a CNAME or A record.",
  },
  {
    site: "docs.example.org",
    title: "How DNS propagation works",
    description: "Resolvers cache records for their TTL, so a change can take up to a day to show.",
  },
];

export default function CitationInline() {
  return (
    <p className="max-w-md text-sm text-foreground">
      Point www.example.com at your site with a CNAME record{"\u00a0"}
      {sources.map((source, index) => (
        <Citation key={source.title}>
          <CitationTrigger
            href="#"
            onClick={preventNavigation}
            aria-label={`Source ${index + 1}: ${source.title}`}
          >
            {index + 1}
          </CitationTrigger>
          <CitationContent>
            <CitationSource>
              <GlobeIcon />
              {source.site}
            </CitationSource>
            <CitationTitle>{source.title}</CitationTitle>
            <CitationDescription>{source.description}</CitationDescription>
          </CitationContent>
        </Citation>
      ))}
      . It usually works within a few minutes.
    </p>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/citation
```

## Usage

```tsx
import {
  Citation,
  CitationContent,
  CitationDescription,
  CitationSource,
  CitationTitle,
  CitationTrigger,
} from "@/components/ui/citation";

export function Cited() {
  return (
    <p>
      Each key can make 100 requests a minute{" "}
      <Citation>
        <CitationTrigger
          href="https://example.com/docs/rate-limits"
          aria-label="Source 1: Rate limits"
        >
          1
        </CitationTrigger>
        <CitationContent>
          <CitationSource>example.com</CitationSource>
          <CitationTitle>Rate limits</CitationTitle>
          <CitationDescription>Each API key can make 100 requests a minute.</CitationDescription>
        </CitationContent>
      </Citation>
      .
    </p>
  );
}
```

A citation is a [Hover Card](https://ui.jarv.is/components/hover-card.md). `CitationTrigger` is a small numbered link in
the text that opens the source on another site in a new tab. `CitationContent` previews the source
while someone hovers over or focuses the link. On a touch screen, the first tap shows the preview
and a second tap follows the link.

Give the trigger an `aria-label` that starts with its number and names the source, such as
`Source 1: Rate limits`. The number alone doesn't say what the link cites, and a label that
includes the number still matches what voice control users see.

Put a space before the citation, as a model's reply does. The marker stays on the same line as the
word before it, and punctuation after the marker stays on its line too. Adjacent markers sit 4px
apart.

## Composition

- `Citation`
  - `CitationTrigger`
  - `CitationContent`
    - `CitationSource`
    - `CitationTitle`
    - `CitationDescription`

## Examples

### In a reply

Models cite sources with numbered links, such as `[1](https://example.com/docs/rate-limits)`. Pass
[Markdown](https://ui.jarv.is/components/markdown.md) a link component that renders a citation for each URL you have a
source for and falls back to `MarkdownLink` for the rest. The AI SDK sends the sources a reply used
as `source-url` parts, each with a `url` and `title`. TanStack AI doesn't send sources, so take them
from the output of the tool that found them.

```tsx
"use client";

import { GlobeIcon } from "lucide-react";

import {
  Citation,
  CitationContent,
  CitationDescription,
  CitationSource,
  CitationTitle,
  CitationTrigger,
} from "@/components/ui/citation";
import { Markdown, MarkdownLink } from "@/components/ui/markdown";
import { preventNavigation } from "@/examples/data";

const sources = [
  {
    url: "https://example.com/docs/rate-limits",
    site: "example.com",
    title: "Rate limits",
    description: "Each API key can make 100 requests a minute, with bursts of up to 20 a second.",
  },
  {
    url: "https://example.com/docs/errors",
    site: "example.com",
    title: "Errors",
    description: "A 429 response means you’ve hit a limit. Wait for the Retry-After header.",
  },
];

const reply = `You can make **100 requests a minute** with each key [1](https://example.com/docs/rate-limits). Past that, the API answers with a \`429\` and a \`Retry-After\` header saying how long to wait [2](https://example.com/docs/errors).`;

function Link(props: React.ComponentProps<"a">) {
  const index = sources.findIndex((source) => source.url === props.href);
  const source = sources[index];
  if (!source) return <MarkdownLink {...props} />;

  return (
    <Citation>
      <CitationTrigger
        href={props.href}
        onClick={preventNavigation}
        aria-label={`Source ${index + 1}: ${source.title}`}
      >
        {props.children}
      </CitationTrigger>
      <CitationContent>
        <CitationSource>
          <GlobeIcon />
          {source.site}
        </CitationSource>
        <CitationTitle>{source.title}</CitationTitle>
        <CitationDescription>{source.description}</CitationDescription>
      </CitationContent>
    </Citation>
  );
}

const components = { a: Link };

export default function CitationInMarkdown() {
  return (
    <Markdown components={components} className="w-full max-w-md">
      {reply}
    </Markdown>
  );
}
```

To list every source a reply read, use an expandable [Trace](https://ui.jarv.is/components/trace.md) line.

## Props

| Part | Extends |
| --- | --- |
| `Citation` | [`HoverCard`](https://ui.jarv.is/components/hover-card.md) |
| `CitationTrigger` | [`HoverCardTrigger`](https://ui.jarv.is/components/hover-card.md) |
| `CitationContent` | [`HoverCardContent`](https://ui.jarv.is/components/hover-card.md) |
| `CitationSource` | `<div>` |
| `CitationTitle` | `<div>` |
| `CitationDescription` | `<p>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### Citation

| Prop                    | Type                                                                          | Default | Description                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------- | ----------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultOpen?`          | `boolean`                                                                     | `false` | Whether the preview card is initially open. To render a controlled preview card, use the `open` prop instead.                                                                                                                                                                                                                                                                                      |
| `open?`                 | `boolean`                                                                     | —       | Whether the preview card is currently open.                                                                                                                                                                                                                                                                                                                                                        |
| `onOpenChange?`         | `((open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => void)` | —       | Event handler called when the preview card is opened or closed.                                                                                                                                                                                                                                                                                                                                    |
| `onOpenChangeComplete?` | `((open: boolean) => void)`                                                   | —       | Event handler called after any animations complete when the preview card is opened or closed.                                                                                                                                                                                                                                                                                                      |
| `actionsRef?`           | `React.RefObject<PreviewCardRootActions \| null>`                             | —       | A ref to imperative actions. - `unmount`: Ends the closing phase of the preview card after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the preview card completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. - `close`: Closes the preview card imperatively when called. |
| `handle?`               | `PreviewCardHandle<unknown>`                                                  | —       | A handle to associate the preview card with a trigger. If specified, allows external triggers to control the card's open state. Can be created with the PreviewCard.createHandle() method.                                                                                                                                                                                                         |
| `children?`             | `PayloadChildRenderFunction<unknown> \| React.ReactNode`                      | —       | The content of the preview card. This can be a regular React node or a render function that receives the `payload` of the active trigger.                                                                                                                                                                                                                                                          |
| `triggerId?`            | `string \| null`                                                              | —       | ID of the trigger that the preview card is associated with. This is useful in conjunction with the `open` prop to create a controlled preview card. There's no need to specify this prop when the preview card is uncontrolled (that is, when the `open` prop is not set).                                                                                                                         |
| `defaultTriggerId?`     | `string \| null`                                                              | —       | ID of the trigger that the preview card is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open preview card.                                                                                                                                                                                                                                    |

### CitationTrigger

| Prop           | Type                                                                                                                                                          | Default                  | Description                                                                                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `handle?`      | `PreviewCardHandle<unknown>`                                                                                                                                  | —                        | A handle to associate the trigger with a preview card.                                                                                                                                    |
| `payload?`     | `unknown`                                                                                                                                                     | —                        | A payload to pass to the preview card when it is opened.                                                                                                                                  |
| `delay?`       | `number`                                                                                                                                                      | `600`                    | How long to wait before the preview card opens. Specified in milliseconds.                                                                                                                |
| `closeDelay?`  | `number`                                                                                                                                                      | `300`                    | How long to wait before closing the preview card. Specified in milliseconds.                                                                                                              |
| `openOnTap?`   | `boolean`                                                                                                                                                     | `true`                   | Opens the card when the trigger is tapped on a touch screen, where hovering can't open it. A second tap follows the link, and a tap elsewhere closes the card.                            |
| `newTabLabel?` | `string`                                                                                                                                                      | `"(opens in a new tab)"` | What screen readers announce after a source on another site, which opens in a new tab. Pass an empty string to announce nothing.                                                          |
| `className?`   | `string \| ((state: PreviewCardTriggerState) => string \| undefined)`                                                                                         | —                        | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                      |
| `style?`       | `React.CSSProperties \| ((state: PreviewCardTriggerState) => React.CSSProperties \| undefined)`                                                               | —                        | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                   |
| `render?`      | `ComponentRenderFn<React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, PreviewCardTriggerState> \| React.ReactElement` | —                        | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### CitationContent

| Prop                     | Type                                                                                                                 | Default                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `keepMounted?`           | `boolean`                                                                                                            | `false`                | Whether to keep the portal mounted in the DOM while the popup is hidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `container?`             | `HTMLElement \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| ShadowRoot \| null`                            | —                      | A parent element to render the portal element into.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `anchor?`                | `Element \| React.RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null` | —                      | An element to position the popup against. By default, the popup will be positioned against the trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `positionMethod?`        | `"absolute" \| "fixed"`                                                                                              | `'absolute'`           | Determines which CSS `position` property to use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `side?`                  | `"bottom" \| "inline-end" \| "inline-start" \| "left" \| "right" \| "top"`                                           | `"bottom"`             | Which side of the anchor element to align the popup against. May automatically change to avoid collisions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sideOffset?`            | `number \| OffsetFunction`                                                                                           | `4`                    | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `align?`                 | `"center" \| "end" \| "start"`                                                                                       | `"start"`              | How to align the popup relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `alignOffset?`           | `number \| OffsetFunction`                                                                                           | `0`                    | Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `collisionBoundary?`     | `Boundary`                                                                                                           | `'clipping-ancestors'` | An element or a rectangle that delimits the area that the popup is confined to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `collisionPadding?`      | `Padding`                                                                                                            | `5`                    | Additional space to maintain from the edge of the collision boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `sticky?`                | `boolean`                                                                                                            | `false`                | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `arrowPadding?`          | `number`                                                                                                             | `5`                    | Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disableAnchorTracking?` | `boolean`                                                                                                            | `false`                | Whether to disable the popup from tracking any layout shift of its positioning anchor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `collisionAvoidance?`    | `CollisionAvoidance`                                                                                                 | —                      | Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): - `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`). - `'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - `'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows. - `'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - `'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR). - `'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR). - `'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`. |
| `className?`             | `string \| ((state: PreviewCardPopupState) => string \| undefined)`                                                  | —                      | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `style?`                 | `React.CSSProperties \| ((state: PreviewCardPopupState) => React.CSSProperties \| undefined)`                        | —                      | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `render?`                | `ComponentRenderFn<HTMLProps, PreviewCardPopupState> \| React.ReactElement`                                          | —                      | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### CitationSource

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### CitationTitle

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### CitationDescription

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
