react-native-streaming-message-list
ChatGPT and Claude-style smart scrolling for React Native message lists.
A FlatList-compatible React Native component that replicates ChatGPT/Claude-like "new message snaps to top" scrolling behavior for conversational UIs where the last item can grow over time (e.g., streaming AI responses).
Try it live on Expo Snack:
Android •
iOS •
Web
## Features
- **Smart scroll behavior**: New messages snap to top with dynamic blank space management
- **Streaming-friendly**: Handles growing/updating content without scroll jank
- **FlatList-like API**: Familiar props, works with any message data structure
## Installation
```sh
npm install react-native-streaming-message-list react-native-reanimated
```
This library requires [react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/). Follow their installation guide if you haven't already.
## Examples
We provide multiple example apps showcasing different use cases:
- **[Basic Example](./examples/basic/)** - Simple, minimal implementation showing core functionality
- **[ChatGPT Example](./examples/chatgpt/)** - ChatGPT-inspired UI
See the [examples README](./examples/README.md) for how to run and switch between demos.
## Quick Start
> 💡 **For a complete working example**, check out the [examples folder](./examples).
### 1. Replace your list component
Replace `FlatList` with `StreamingMessageList`. This component is built on [`@legendapp/list`](https://github.com/LegendApp/legend-list) and accepts the same FlatList-like props:
```diff
- import { FlatList } from 'react-native';
+ import { StreamingMessageList } from 'react-native-streaming-message-list';
- item.id}
renderItem={renderMessage}
/>
```
### 2. Add streaming state
Create a state variable to track when messages are actively streaming:
```tsx
const [isStreaming, setIsStreaming] = useState(false);
```
Pass it to `StreamingMessageList`:
```diff
item.id}
renderItem={renderMessage}
+ isStreaming={isStreaming}
/>
```
### 3. Wrap your anchor and streaming items
To enable smart scrolling, wrap two special messages:
- **Last user message**: Wrap with `AnchorItem` (this message will stay near the top)
- **Last assistant message**: Wrap with `StreamingItem` (tracks height changes during and after streaming)
```tsx
import { AnchorItem, StreamingItem } from 'react-native-streaming-message-list';
const renderMessage = ({ item, index }) => {
const isLastUserMessage =
item.role === 'user' &&
messages.findLastIndex(m => m.role === 'user') === index;
const isLastAssistantMessage =
item.role === 'assistant' &&
messages.findLastIndex(m => m.role === 'assistant') === index;
let content = ;
if (isLastUserMessage) {
content = {content};
} else if (isLastAssistantMessage) {
content = {content};
}
return content;
};
```
That's it! The list will now handle ChatGPT-style scrolling automatically.
---
**Need more?** See the [examples folder](./examples) for complete, runnable chat apps with different UI styles.
## Common Patterns
### When to use each component
- **`StreamingMessageList`**: Your main list component. Use it instead of `FlatList` for any chat/message list where content can stream or grow.
- **`AnchorItem`**: Wrap the **last user message**. This keeps it visible near the top while the assistant response grows below it.
- **`StreamingItem`**: Wrap the **last assistant message**. Keep this wrapper even after streaming ends to track height changes (like action buttons appearing).
### Optional animations
For message animations, use `Animated.View` from `react-native-reanimated` with the `entering` prop.
**Recommended approach:** Animate only the first user message with a fade-in. The "slide-in" effect for new messages happens naturally through the library's placeholder and scroll-to-bottom behavior, so additional slide animations are unnecessary:
```tsx
import Animated, { FadeIn } from 'react-native-reanimated';
const renderMessage = ({ item, index }) => {
const isFirstUserMessage =
item.role === 'user' &&
messages.findIndex(m => m.role === 'user') === index;
let content = ;
return (
{content}
);
};
```
See the [Reanimated documentation](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/entering-exiting-animations/) for more animation options.
### Typical message flow
1. User sends a message → mark it as `AnchorItem`
2. Assistant starts responding → set `isStreaming={true}` and wrap the new assistant message with `StreamingItem`
3. Assistant finishes → set `isStreaming={false}`
4. Repeat for the next turn
### Scroll to bottom button
Use `useStreamingMessageList` to show a button when the user scrolls away from the bottom:
```tsx
import {
StreamingMessageList,
StreamingMessageListProvider,
useStreamingMessageList,
} from 'react-native-streaming-message-list';
const ScrollToBottomButton = ({ listRef }) => {
const { isAtEnd, contentFillsViewport } = useStreamingMessageList();
if (isAtEnd || !contentFillsViewport) return null;
return (
listRef.current?.scrollToEnd({ animated: true })}
>
↓
);
};
const listRef = useRef(null);
```
## API
### ``
Main component that wraps your message list with smart scroll behavior.
#### Props
Extends all `FlatList` props from `@legendapp/list`, plus:
| Prop | Type | Required | Description |
| -------------- | ---------------------------- | -------- | ------------------------------------------------------------- |
| `data` | `T[]` | Yes | Array of message items |
| `renderItem` | `(info) => ReactNode` | Yes | Function to render each item |
| `keyExtractor` | `(item, index) => string` | Yes | Unique key for each item |
| `isStreaming` | `boolean` | No | Whether content is currently updating (triggers smart scroll) |
| `config` | `StreamingMessageListConfig` | No | Advanced configuration |
#### Config Options
```typescript
type StreamingMessageListConfig = {
debounceMs?: number; // Debounce for placeholder height calculations (default: 150)
placeholderStableDelayMs?: number; // Delay before placeholder is considered stable (default: 200)
isAtEndThreshold?: number; // Threshold in pixels for isAtEnd calculation (default: 10)
};
```
### ``
Wrapper for the message that should be "anchored" near the top when a new conversation turn begins (typically the last user message).
```tsx
```
### ``
Wrapper for the last assistant message.
```tsx
```
### ``
Optional provider that enables access to scroll metrics via `useStreamingMessageList`. Wrap your list and any components that need scroll metrics with this provider.
```tsx
```
### `useStreamingMessageList()`
Hook to access scroll metrics. Must be used within `StreamingMessageListProvider`.
```tsx
import { useStreamingMessageList } from 'react-native-streaming-message-list';
const { isAtEnd, contentFillsViewport } = useStreamingMessageList();
```
| Property | Type | Description |
|----------|------|-------------|
| `isAtEnd` | `boolean` | `true` when scrolled to bottom (within threshold) |
| `contentFillsViewport` | `boolean` | `true` when content height exceeds viewport |
## How It Works
The component implements ChatGPT-style scrolling by:
1. **Measuring heights**: Tracks the "anchor" message (last user message) and "streaming" content (growing assistant response)
2. **Dynamic placeholder**: Injects blank space at the bottom so the anchor message lands near the top
3. **Auto-scrolling**: Automatically scrolls to show new messages
4. **Debounced updates**: Prevents jank during rapid content updates
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
MIT
---
Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)