# ThreadList

`ThreadList` lists the threads the current user takes part in. It reads `client.threads`, the thread manager, and renders one [`ThreadListItem`](https://getstream.io/chat/docs/sdk/react/component-reference/thread-list/threadlistitem/) per thread. [Thread list UI](https://getstream.io/chat/docs/sdk/react/ui/components/thread-list-ui/) describes what it shows, and [The user's threads](https://getstream.io/chat/docs/sdk/react/state/channels-and-threads/what-channels-and-threads-hold/#the-users-threads) how the list loads and stays current.

## Best practices

- Render it anywhere inside `Chat`. It needs no `Channel`.
- Render one `ThreadList` at a time. Each one reloads the list when it mounts, and deactivates `client.threads` when it unmounts, even while another list is still on screen.
- Change the rows through the `ThreadListItemUI` override key. Keep `ThreadListItem`, which gives each row its thread.
- Keep rows light. The list is virtualized with `react-virtuoso`, so rows mount and unmount as the user scrolls.
- Clicking a row opens the thread through `useWorkspaceNavigation()`. Without a layout that does nothing, so use `ChatView` or provide your own navigation, as in [Threads without ChatView](https://getstream.io/chat/docs/sdk/react/features/messaging/replies-and-threads/#threads-without-chatview).

## Basic usage

```tsx
import { Chat, ThreadList } from "stream-chat-react";

export const ThreadsPage = () => (
  <Chat client={client}>
    <ThreadList />
  </Chat>
);
```

`ThreadList` renders, from top to bottom:

- the `ThreadListHeader` override, `<ThreadListHeader/>` by default, with the "Threads" title;
- `ThreadListUnseenThreadsBanner`, while threads outside the list have new replies;
- the rows, a `ThreadListItem` for each thread in `client.threads.paginator`;
- `ThreadListLoadingIndicator` after the last row while the next page loads, or `ThreadListEmptyPlaceholder` when there are no threads;
- a `NotificationList` for the `thread-list` panel.

While the first page loads, it shows the `FirstPageLoadingIndicator` override instead of the rows, `LoadingChannels` by default. When the first page fails to load, it shows the `ListLoadErrorIndicator` override instead, with "Couldn't load threads" and a "Try again" button by default. A failed query also publishes an `api:thread:query:failed` notification in the `thread-list` panel. [List states UI](https://getstream.io/chat/docs/sdk/react/ui/components/list-states-ui/) explains these states.

## Selection in a ChatView workspace

With `ChatView`, render `ThreadList` in the threads view, next to a `ThreadSlot`. Clicking a row calls `openThread(thread)`, and `ChatView` puts the thread in the view's thread slot. ⌘/ctrl-click asks the layout to open it beside the open one. The row of an open thread is marked with `aria-selected`.

```tsx
import {
  MessageComposer,
  MessageList,
  ThreadHeader,
  ThreadList,
} from "stream-chat-react";
import { ChatView, ThreadSlot } from "stream-chat-react/slot-layout";

// Pass it to ChatView as `views={{ threads: <ThreadsView /> }}`, with a
// "thread" slot in the threads layout.
export const ThreadsView = () => (
  <>
    <ChatView.Selector />
    <ThreadList />
    <ThreadSlot slot="thread">
      <ThreadHeader />
      <MessageList />
      <MessageComposer />
    </ThreadSlot>
  </>
);
```

The [Quick start](https://getstream.io/chat/docs/sdk/react/getting-started/quick-start/#add-threads) builds the whole layout, and [Workspace with ChatView](https://getstream.io/chat/docs/sdk/react/ui/layout/workspace-with-chatview/) explains views and slots.

## Override keys

`ThreadList` reads these keys from `WithComponents`. [Thread list UI](https://getstream.io/chat/docs/sdk/react/ui/components/thread-list-ui/#replacing-parts) shows a replacement row.

| Override key                    | Replaces                                          | Props                                                                                                                  |
| ------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ThreadListItem`                | The whole row                                     | `ThreadListItemProps`                                                                                                  |
| `ThreadListItemUI`              | The row's look, inside `ThreadListItem`           | `ThreadListItemUIProps`                                                                                                |
| `ThreadListUnseenThreadsBanner` | The banner that reloads the list                  | none                                                                                                                   |
| `FirstPageLoadingIndicator`     | The placeholder rows while the first page loads   | none                                                                                                                   |
| `ListLoadErrorIndicator`        | The rows, when the first page failed to load      | `ListLoadErrorIndicatorProps`                                                                                          |
| `ThreadListLoadingIndicator`    | The spinner after the last row                    | none                                                                                                                   |
| `ThreadListEmptyPlaceholder`    | What shows when there are no threads              | none                                                                                                                   |
| `ThreadListHeader`              | The list header, `<ThreadListHeader/>` by default | none. [Thread list UI → Header](https://getstream.io/chat/docs/sdk/react/ui/components/thread-list-ui/#header) adds content to the default |
| `NotificationList`              | The notifications shown over the list             | `NotificationListProps`                                                                                                |

## Props

| Prop            | Type                             | Default | Description                                                                                                                                                                                                             |
| --------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `virtuosoProps` | `VirtuosoProps<Thread, unknown>` | none    | Props for the underlying [`Virtuoso`](https://virtuoso.dev/virtuoso-api/interfaces/VirtuosoProps/) list. They're applied last, so they replace the SDK's own, such as `atBottomStateChange`, which loads the next page. |

## Related hooks

| Hook                         | Returns                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `useThreadList()`            | nothing. Reloads `client.threads` and keeps it active while the page is visible. `ThreadList` calls it. |
| `useThreadListItemContext()` | the thread of the row being rendered, or `undefined` outside a row                                      |
| `useWorkspaceNavigation()`   | `openThread` and `isThreadActive`, which the rows use to open a thread and mark the open one            |

The thread list's own stores have no hook. Read `client.threads.paginator.state` for the threads and `client.threads.state` for `unreadThreadCount` and `unseenThreadIds` with `useStateStore`. See [useThreadList](https://getstream.io/chat/docs/sdk/react/reference/hooks/loading-data-hooks/#usethreadlist), [useThreadListItemContext](https://getstream.io/chat/docs/sdk/react/reference/hooks/state-and-entity-hooks/#usethreadlistitemcontext) and [Thread and thread manager](https://getstream.io/chat/docs/sdk/react/reference/state/thread-and-thread-manager/).

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/component-reference/thread-list/threadlist/](https://getstream.io/chat/docs/sdk/react/component-reference/thread-list/threadlist/).