# Source List

Numbered sources pinned to a chat; citations like [1] in answers point here.

- Category: AI & Agents
- Page: https://wunderui.com/components/source-list
- Tier: Core and Pro

## Install

Source List ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { SourceList } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { SourceList } from "@wunderui/react"

const sources = [
  { title: "q3-report.pdf", meta: "File · 2.4 MB", kind: "file" },
  { title: "Pricing, WunderUI", meta: "wunderui.com · web page", kind: "web", href: "https://wunderui.com/pricing" },
] as const

export function Sources() {
  return <SourceList id="answer-sources" sources={[...sources]} />
}
```

Expected result: You see a card titled Sources with 2 pinned and two numbered rows. The second row is a link.

## When to use

### Use Source List for

- The sources an answer used, with numbers that match the citations in the text
- A set of pinned files, documents, web pages and channels in a chat
- A list the reader can open in a new tab

### Use something else

- [Chat Source](https://wunderui.com/components/chat-source) for one source as a chip inside a message
- [Search Result Card](https://wunderui.com/components/search-result-card) for a ranked web result with a snippet and a relevance
- [Context Pill](https://wunderui.com/components/context-pill) for what is attached to a prompt before it is sent

## Keyboard

Only the rows that are links take part. The list itself handles no keys.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves through the linked rows in order. A row that is not a link is not a stop. |
| `Enter` | Follows the link of the focused row, in a new tab. |

## Behavior

What the list does with numbers, links, text and assistive technology.

- **Numbers:** A row's number is its place in the array plus one, and you can't set it. With a list id, each row gets an id from it plus its number, so a citation can link to it.
- **Links:** A source with an http(s) or relative link opens in a new tab without exposing the opener, and the row doesn't say so, so mention it in the meta line if it matters. Any other link draws a plain row.
- **Count:** The header reads N pinned for the rows drawn, such as 1 pinned or 7 pinned. Set `countLabel` to use another word, or an empty string to hide it.
- **Empty:** An empty array draws the header with 0 pinned and an empty list. There is no empty text, so draw your own sentence instead of the list.
- **Kinds:** Kind picks the icon: web (default), file, doc or channel. The icon is the only visual of a source, with no favicon and no loading state.
- **Long text:** Titles and meta lines wrap and nothing is cut. A long list title wraps in the header beside the count.
- **Assistive technology:** The section is named by the title when it is a string, otherwise Sources. The title is a fixed h3, so place the list under an h2.
- **Motion:** The list has no motion. A link row changes nothing on hover, only its focus ring appears.
- **Reduced motion:** There is nothing to reduce.

## Anatomy

- `SourceList`: A section with a 1 px border and a 16 px radius, named by the title when it is a string, otherwise Sources. It is as wide as its container.
- `Title`: The title in 14 px semibold, Sources by default.
- `Count`: N pinned, the number of rows drawn, in 12 px tertiary text. `countLabel` replaces the word and an empty string hides the count.
- `Row`: One item of an ordered list with a hairline above it. With a list id each row gets that id plus its number, and a source with an http(s) or relative link is an anchor, any other a span.
- `Number`: A 20 px indigo tint circle with the place of the source in the array, starting at 1. A citation points to this number.
- `Icon`: A decorative 16 px Lucide icon by kind: a globe for web (the default), a file, a document or a channel. There is no favicon.
- `Text`: The title in 14 px medium and an optional meta line in 12 px secondary text, for the domain, size or editor. Both wrap.

## Best practices

### When to use

- Use it for the sources of one answer or chat, numbered to match the citations in the text. For one source drawn as a chip inside a message use Chat Source.

### Do

- Number citations from the same array. Link citation 2 to the row with id answer-sources-2, so both numbers cannot drift apart.
- Put the domain, size or editor in the meta line. There is no favicon, so the line under the title is where a person sees where a source comes from.
- Pass a link only for http(s) and relative addresses. Anything else, such as file, mailto, javascript or data, is drawn as a plain row, so a source from the open web cannot run code.
- Cut a long list yourself. Slice the array from the start so numbers still match the citations, and add a button saying how many are hidden, like Show 3 more.
- Draw the list only when there is something to list. Say No sources were used for this answer or show skeleton rows while sources are looked up.

### Don't

- Don't pass an empty array. The list draws its header with 0 pinned and nothing else.
- Don't reorder the array after the answer was written. The numbers in the text are places in the array.
- Don't use a long sentence as the title. It sits beside the count on one row and wraps, so keep it to a word or two.

## API reference

### SourceList

| Prop | Type | Default | Description |
|---|---|---|---|
| sources* | Source[] |  | The sources, in order. Each has a `title`, an optional `meta` line, an optional `kind` (`web`, `file`, `doc` or `channel`, default `web`) and an optional `href`. The place in the array is the number. |
| className | string |  | Extra classes for the list, for example a maximum width. |
| countLabel | string | "pinned" | The word after the count in the header ("3 pinned"). Pass an empty string to hide the count. |
| highlight | number |  | 1-based number of the source a citation points at right now. It gets a subtle fill and `aria-current`. |
| id | string |  | Gives the rows ids: `<id>-1`, `<id>-2` and so on, for citations to link to. Without it the rows have no id. |
| title | React.ReactNode | "Sources" | The heading of the list. Default `Sources`. When it is a string it also names the section for assistive technology. |

## Examples

### Links: only http(s) sources become links

### Amount: one, three, seven or none

### Header: the title above the list

### Text: long titles and meta lines wrap

### Own count label and a highlighted source

## In context

### An answer with citations: the number in the text is the number of the row

Every row gets the id you pass plus its number, so a citation can link to it. Both numbers come from the same array, so they cannot drift apart.

### More sources than fit: the app cuts the list and adds a button

The list shows every source it is given. To show four of seven, cut the array from the start so the numbers still match the citations, and add a button saying how many are hidden.

### Searching, no sources, found: draw the list only when there is something to list

An empty array draws a header that says 0 pinned and nothing else. While sources are being looked up, or when an answer used none, say so in a sentence instead.

## For AI agents

`get_component("source-list")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
