# Inline Citation (/docs/agent-ui/components/inline-citation)

Use an inline citation inside a response's text, right after the claim it supports, so readers can check a source without leaving the sentence. It's a small marker that keeps the paragraph's line height, and its card shows each source's host name, title and snippet. Several sources page in one card.

<Example caption="Rest the pointer on 1 or 2, focus one with Tab, or press it, to open its card. In the card for 1, press Next to see the second source. Press Escape to close it.">
<j />

```tsx
import { InlineCitation } from "@/components/ui/inline-citation";
import { Message, MessageContent } from "@/components/ui/message";

const limits = [
  {
    id: "rate-limits",
    title: "Rate limits for the REST API",
    url: "https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api",
    snippet: "Primary rate limits cap how many requests you can make in an hour.",
  },
  {
    id: "best-practices",
    title: "Best practices for using the REST API",
    url: "https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api",
    snippet: "Wait at least one minute before retrying when you hit a secondary rate limit.",
  },
];

const retryAfter = [
  {
    id: "retry-after",
    title: "Retry-After header",
    url: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After",
    snippet: "How long the user agent should wait before making a follow-up request.",
  },
];

export default function InlineCitationExample() {
  return (
    <Message aria-label="Assistant message" messageRole="assistant" className="w-full max-w-xl">
      <MessageContent>
        <p>
          The API allows 5,000 requests an hour for a signed-in user{" "}
          <InlineCitation sources={limits} label="1" />. When you hit the limit, wait as long as the{" "}
          <code>Retry-After</code> header says before trying again{" "}
          <InlineCitation sources={retryAfter} label="2" />.
        </p>
      </MessageContent>
    </Message>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/inline-citation
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/inline-citation-web
```

## Composition [#composition]

```text
InlineCitation
├── InlineCitationTrigger
└── InlineCitationContent
    ├── InlineCitationItem
    └── InlineCitationCarousel
        ├── InlineCitationItem
        │   ├── InlineCitationLink
        │   │   ├── InlineCitationHost
        │   │   └── InlineCitationSourceTitle
        │   └── InlineCitationSnippet
        ├── InlineCitationPrevious
        ├── InlineCitationIndex
        └── InlineCitationNext
```

`InlineCitationTrigger` is the marker, a native button that shows the `label`. `InlineCitationContent` is the card. With one source it holds that source's `InlineCitationItem`; with more, `InlineCitationCarousel` is UI SDK's Carousel with a slide per source and **Previous**, the page ("1 of 3") and **Next** below. `InlineCitationLink` links to the source's `url` and opens it in a new tab. `InlineCitationHost` shows the host name without `www.`, `InlineCitationSourceTitle` the `title`, up to two lines, and `InlineCitationSnippet` the `snippet`, up to three. Every part renders a `span`, so a citation is valid inside a `p`. To arrange the parts yourself, pass them as children of `InlineCitation`.

## Usage [#usage]

### Sources [#sources]

Pass `sources`, each with an `id` and a `title`, and optionally a `url` and `snippet`. Links accept `http`, `https`, `mailto` and relative URLs. A source with any other URL, like `javascript:`, shows as text with no link and no host name.

```tsx
<p>
  Retry after a minute <InlineCitation sources={[{ id: "limits", title: "Rate limits", url: "https://docs.github.com/en/rest" }]} label="1" />.
</p>
```

### The Marker [#the-marker]

Pass `label` to number the marker, like `"1"`. Without it, the marker shows the first source's host name, with "+N" for the others, like "docs.github.com +1". The marker is sized from the text around it and is shorter than its line, so it never changes the paragraph's line height. Screen readers hear its text, then its source, like "1, Source: Retry-After header", or "1, Sources: 2" for more than one.

### Opening [#opening]

The card opens when the pointer rests on the marker for 600 ms, when keyboard focus rests on it as long, and when it's pressed, by pointer, Enter or Space. It closes on Escape, a press outside or focus leaving the citation, and 300 ms after the pointer leaves both the marker and the card when the pointer opened it. Opening it leaves focus on the marker; Tab moves into the card.

Pass `open` and `onOpenChange` to control it, or `defaultOpen` to start with it open. `onOpenChange` gets UI SDK Popover's reason, like `trigger-hover`, `trigger-press` or `escape-key`, or `trigger-focus` when keyboard focus opened it.

### Paging [#paging]

With more than one source, **Previous** and **Next** page through them, as do the arrow keys while the slides are focused, and the page below reads "1 of 3". Every source takes the card's full width and the card is as tall as its tallest source, so paging never moves the controls. Swiping and dragging are off, so a scroll inside the card never pages it. The card opens again on the source it last showed.

### Motion [#motion]

The card rises and fades in. Under `prefers-reduced-motion`, or with `motion="reduced"`, it only fades, over 120 ms, and with `motion="none"` it shows at once. Paging scrolls smoothly unless the reader prefers reduced motion.

## API Reference [#api-reference]

### InlineCitationOptions

| Prop            | Type                                                                                             | Description                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `sources?`      | `Source[] \| undefined`                                                                          | The sources the citation points to, in the order the card pages through them. Defaults to none.                                         |
| `label?`        | `string \| undefined`                                                                            | The marker's text, like `"1"`. Defaults to the first source's host name, or its title without a safe `url`, with "+N" for the others.   |
| `open?`         | `boolean \| undefined`                                                                           | Whether the card is open. Passing it controls it: change it in `onOpenChange`.                                                          |
| `defaultOpen?`  | `boolean \| undefined`                                                                           | Whether the card is open at first, when `open` isn't passed. Default: `false`                                                           |
| `onOpenChange?` | `((open: boolean, details: ChangeDetails<InlineCitationOpenChangeReason>) => void) \| undefined` | Called when the card opens or closes, with what caused it.                                                                              |
| `motion?`       | `"auto" \| "none" \| "reduced"`                                                                  | How the card opens: at full motion it rises in; reduced motion only fades. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"` |

### Agent [#agent]

An agent connected with `createAgent` finds the citation by the marker's name, like "1, Sources: 2", and reads whether its card is open. `open` is offered while the card is closed and `close` while it's open. While it's open, `next` is offered when a source follows and `previous` when one comes before. Like any component with a button, it also has UI SDK's generic `press`.

### InlineCitationAgentActions

| Prop       | Type                           | Description                                                                                                    |
| ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `open`     | `(() => boolean) \| undefined` | Opens the card. Offered only while it's closed. Returns whether the change was accepted.                       |
| `close`    | `(() => boolean) \| undefined` | Closes the card. Offered only while it's open. Returns whether the change was accepted.                        |
| `next`     | `(() => boolean) \| undefined` | Shows the next source. Offered while the card is open and a source follows. Returns whether it moved.          |
| `previous` | `(() => boolean) \| undefined` | Shows the previous source. Offered while the card is open and a source comes before. Returns whether it moved. |

<Caption>
Runs in React and Web Components. On `<kind-inline-citation>`, set `sources` as a property; the other props are kebab-case attributes, and `onOpenChange` is the `openchange` event. The element fills in its marker and card, with one item or a Carousel as the sources need.
</Caption>