# ThreadList

Renders threads and lets you handle selection. Must be rendered inside [`Chat`](/chat/docs/sdk/react-native/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

| Prop                      | Description                                                                                                                                                                                                                                                                                                                     | Type                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `additionalFlatListProps` | An object containing [`FlatListProps`](https://reactnative.dev/docs/flatlist#props) that can be used to override the default ones provided in the `ThreadList`.                                                                                                                                                                 | `object`                             |
| `onThreadSelect`          | A callback invoked whenever a thread in the list is clicked. Can be used to navigate to a thread screen. The callback receives `(thread, channel)` where `thread` contains `thread` (parent message) and `threadInstance` ([`Thread` class](https://github.com/GetStream/stream-chat-js/blob/master/src/thread.ts)) properties. | `(thread, channel) => Promise<void>` |
| `isFocused`               | Whether the `ThreadList` is currently in focus. Controls when updates to the list are active. Best used with hooks from navigation libraries (such as [`useIsFocused()` from React Navigation](https://reactnavigation.org/docs/use-is-focused/)) for lazy loading.                                                             | `boolean`                            |

## UI Component Props

| Prop                             | Description                                                                                                                                                                                                                                               | Type            |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `ThreadListItem`                 | Custom component to render a single thread item. Defaults to [`DefaultThreadListItem`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadListItem.tsx).                                             | `ComponentType` |
| `ThreadListEmptyPlaceholder`     | Custom component to render the empty placeholder when there are no threads. Defaults to [`DefaultThreadListEmptyPlaceholder`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadList.tsx).          | `ComponentType` |
| `ThreadListLoadingIndicator`     | Custom component to render the loading indicator when `isLoading` is `true`. Defaults to [`DefaultThreadListLoadingIndicator`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadList.tsx).         | `ComponentType` |
| `ThreadListLoadingMoreIndicator` | Custom component to render the loading indicator when `isLoadingNext` is `true`. Defaults to [`DefaultThreadListLoadingMoreIndicator`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadList.tsx). | `ComponentType` |
| `ThreadListUnreadBanner`         | Custom component to render the unread threads banner at the top of the list. Defaults to [`ThreadListUnreadBanner`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadListUnreadBanner.tsx).        | `ComponentType` |
| `ThreadList`                     | Custom component to render the entire `ThreadList`. Defaults to [`ThreadList`](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ThreadList/ThreadList.tsx).                                                         | `ComponentType` |

## Examples

### Using `isFocused` with React Navigation

```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} />;
};
```


---

This page was last updated at 2026-05-13T13:38:50.339Z.

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