# Sources (/docs/agent-ui/components/sources)

Use sources under a response that searched the web or read documents, so readers can check where an answer came from. It shows "Used N sources", and opens into a link for each source with its site's icon, title and host name.

<Example caption="Press Used 3 sources, or focus it and press Enter or Space, to show the links. Press it again to hide them.">
<h />

```tsx
import { Sources } from "@/components/ui/sources";

const sources = [
  {
    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: "retry-after",
    title: "Retry-After header",
    url: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After",
    favicon: "https://developer.mozilla.org/favicon-48x48.png",
    snippet: "How long to wait before making the next request.",
  },
  {
    id: "rfc",
    title: "RFC 9110: HTTP Semantics",
    url: "https://www.rfc-editor.org/rfc/rfc9110",
  },
];

export default function SourcesExample() {
  return <Sources sources={sources} className="w-full max-w-md" />;
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Sources
├── SourcesTrigger
└── SourcesContent
    └── SourcesList
        └── SourcesItem
            ├── SourcesLink
            │   ├── SourcesIcon
            │   ├── SourcesTitle
            │   └── SourcesHost
            └── SourcesSnippet
```

`SourcesTrigger` is a native button that shows the `label`, else "Used N sources", and shows or hides `SourcesContent`. `SourcesList` renders a `SourcesItem` for each source, keyed by its `id`. `SourcesLink` links to the source's `url` and opens it in a new tab. `SourcesIcon` shows the source's `favicon`, and the first letter of its host name until the image loads or without one. `SourcesHost` shows the host name without `www.`, and `SourcesSnippet` the `snippet`, up to two lines. To arrange the parts yourself, pass them as children of `Sources`.

## Usage [#usage]

### Sources [#sources]

Pass `sources`, each with an `id` and a `title`, and optionally a `url`, `favicon` 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
<Sources
  sources={[
    { id: "limits", title: "Rate limits for the REST API", url: "https://docs.github.com/en/rest" },
    { id: "notes", title: "Meeting notes" },
  ]}
/>
```

### Streaming Sources [#streaming-sources]

Add sources as the agent finds them, keeping each `id`. A source added after the list first renders fades up once, and the count in the trigger updates without moving anything around it. A source whose title or URL changes updates in place, without fading in again. At full motion the list slides open; under `prefers-reduced-motion`, or with `motion="reduced"`, it fades in over 120 ms, and with `motion="none"` it shows at once.

### Opening [#opening]

The list starts closed. Pass `defaultOpen` to start with it shown, or `open` with `onOpenChange` to control it; `onOpenChange` gets `"trigger-press"`, `"find-in-page"` or `"imperative"`. The list stays in the page while it's closed, so the browser's find in page reaches it and opens it.

## API Reference [#api-reference]

### SourcesOptions

| Prop            | Type                                                                                      | Description                                                                      |
| --------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `sources?`      | `Source[] \| undefined`                                                                   | The sources, in order. Keep each one's `id` as the list grows. Defaults to none. |
| `label?`        | `string \| undefined`                                                                     | The trigger's text, which also names the list. Defaults to "Used N sources".     |
| `open?`         | `boolean \| undefined`                                                                    | Whether the list shows. Passing it controls it: change it in `onOpenChange`.     |
| `defaultOpen?`  | `boolean \| undefined`                                                                    | Whether the list shows at first, when `open` isn't passed. Default: `false`      |
| `onOpenChange?` | `((open: boolean, details: ChangeDetails<SourcesOpenChangeReason>) => void) \| undefined` | Called when the list opens or closes, with what caused it.                       |
| `motion?`       | `"auto" \| "none" \| "reduced"`                                                           | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                     |

### Agent [#agent]

An agent connected with `createAgent` finds the sources by the trigger's text and reads `open`. `expand()` is offered while the list is hidden and `collapse()` while it shows. Like any component with a button, it also has UI SDK's generic `press`.

### SourcesAgentActions

| Prop       | Type                           | Description                                                                         |
| ---------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| `expand`   | `(() => boolean) \| undefined` | Shows the list. Offered while it's hidden. Returns whether the change was accepted. |
| `collapse` | `(() => boolean) \| undefined` | Hides the list. Offered while it shows. Returns whether the change was accepted.    |

<Caption>
Runs in React and Web Components. On `<kind-sources>`, set `sources` as a property; the other props are kebab-case attributes, and `onOpenChange` is the `openchange` event. The element fills in its trigger, list and items, and keeps any `<kind-sources-item value="…">` you write inside its `<kind-sources-list>`.
</Caption>