# ThreadList

Renders threads and lets you handle selection. Must be rendered inside [`Chat`](/chat/docs/sdk/react-native/v8/core-components/chat/).

## Best Practices

- Render inside `Chat` to ensure thread data and context are available.
- Use `onThreadSelect` for navigation and keep it lightweight.
- Provide empty and loading states for better UX.
- Keep list items simple to maintain scroll performance.
- Use `additionalFlatListProps` sparingly to avoid unexpected list behavior.

## General Usage

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

const App = () => {
  return (
    <OverlayProvider>
      <Chat client={client}>
        <ThreadList />
      </Chat>
    </OverlayProvider>
  );
};
```

## Props

### `additionalFlatListProps`

An object containing [`FlatListProps`](https://reactnative.dev/docs/flatlist#props) that can be used to override the default ones provided in the `ThreadList`.

| Type   |
| ------ |
| object |

### `onThreadSelect`

A method that will be used as a callback whenever a thread in the list is clicked. As an example, it can be used to navigate to a thread screen displaying the thread.

| Type                                 |
| ------------------------------------ |
| `(thread, channel) => Promise<void>` |

The arguments passed are as follows:

#### `thread`

An object containing two properties, `thread` and `threadInstance`. This entire object can be passed as the [`thread` prop](/chat/docs/sdk/react-native/v8/core-components/channel/#thread/) to the `Channel` component.

| Type   |
| ------ |
| object |

The `threadInstance` property is an instance of the [`Thread` class](https://github.com/GetStream/stream-chat-js/blob/master/src/thread.ts).

The `thread` property is a reference to the parent message of the thread.

### `isFocused`

A boolean indicating if the `ThreadList` is currently in focus or not. Essentially a flag that lets us know whether the component is present in the viewport. Whenever present, it controls when updates to the `ThreadList` are active and when they are not. Best used in conjunction with hooks from popular navigation libraries (such as [`useIsFocused()` from React Navigation](https://reactnavigation.org/docs/use-is-focused/)) for lazy loading purposes.

| Type    |
| ------- |
| boolean |

Example:

```tsx
import React from "react";
import { useIsFocused } from "@react-navigation/native";
import { ThreadList } from "stream-chat-react-native";

export const ThreadListScreen = () => {
  const isFocused = useIsFocused();
  return <ThreadList isFocused={isFocused} />;
};
```

### `ThreadListItem`

A custom UI component used to render each item within the `ThreadList`. It will override the UI of the [default `ThreadListItem`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadListItem.tsx) while still keeping all of the data.

| Type          | Default                                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`ThreadListItem`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadListItem.tsx) |

### `ThreadListEmptyPlaceholder`

A custom UI component used to render the empty placeholder if there are no available threads.

| Type          | Default                                                                                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`DefaultThreadListEmptyPlaceholder`](https://github.com/GetStream/stream-chat-react-native/v8/blob/main/package/src/components/ThreadList/ThreadList.tsx) |

### `ThreadListLoadingIndicator`

A custom UI component used to render the loading indicator when `isLoading` is `true`.

| Type          | Default                                                                                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`DefaultThreadListLoadingIndicator`](https://github.com/GetStream/stream-chat-react-native/v8/blob/main/package/src/components/ThreadList/ThreadList.tsx) |

### `ThreadListLoadingMoreIndicator`

A custom UI component used to render the loading indicator when `isLoadingNext` is `true`.

| Type          | Default                                                                                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`DefaultThreadListLoadingMoreIndicator`](https://github.com/GetStream/stream-chat-react-native/v8/blob/main/package/src/components/ThreadList/ThreadList.tsx) |

### `ThreadListUnreadBanner`

A custom UI component used to render the unread threads banner at the top of the list.

| Type          | Default                                                                                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`ThreadListUnreadBanner`](https://github.com/GetStream/stream-chat-react-native/v8/blob/main/package/src/components/ThreadList/ThreadListUnreadBanner.tsx) |

### `ThreadList`

A custom UI component used to render the entire `ThreadList`.

| Type          | Default                                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| ComponentType | [`ThreadList`](https://github.com/GetStream/stream-chat-react-native/v8/blob/main/package/src/components/ThreadList/ThreadList.tsx) |


---

This page was last updated at 2026-04-17T17:33:44.853Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/v8/ui-components/thread-list/](https://getstream.io/chat/docs/sdk/react-native/v8/ui-components/thread-list/).