frameworks/motia/docs/content/docs/development-guide/react-stream-client.mdx
Use @motiadev/stream-client-react to subscribe to Motia streams from React.
npm install @motiadev/stream-client-react
Wrap your app (or a subtree) so hooks can access the stream connection.
import { useMemo } from 'react'
import { MotiaStreamProvider } from '@motiadev/stream-client-react'
export function AppShell({ token }: { token?: string }) {
const protocols = useMemo(() => (token ? ['Authorization', token] : undefined), [token])
return (
<MotiaStreamProvider address="ws://localhost:3112" protocols={protocols}>
<App />
</MotiaStreamProvider>
)
}
address: string - Stream server WebSocket URLprotocols?: string | string[] - Optional WebSocket protocols (for auth tokens, etc.)Access the underlying stream client instance from context.
import { useMotiaStream } from '@motiadev/stream-client-react'
function DebugConnection() {
const { stream } = useMotiaStream()
return <pre>{stream ? 'connected' : 'connecting...'}</pre>
}
Subscribe to all items in a group.
import { useStreamGroup } from '@motiadev/stream-client-react'
type Todo = { id: string; description: string }
function InboxTodos() {
const { data: todos } = useStreamGroup<Todo>({
streamName: 'todo',
groupId: 'inbox',
})
return (
<ul>
{todos.map((todo) => (
<li key={todo.id}>{todo.description}</li>
))}
</ul>
)
}
streamName: string - Stream name from your .stream.ts configgroupId: string - Group to subscribe tosortKey?: keyof TData - Optional sort fieldsetData?: (data: TData[]) => void - Optional callback on updatesSubscribe to one specific stream item.
import { useStreamItem } from '@motiadev/stream-client-react'
type Todo = { id: string; description: string; completedAt?: string }
function TodoDetails({ id }: { id: string }) {
const { data: todo } = useStreamItem<Todo>({
streamName: 'todo',
groupId: 'inbox',
id,
})
if (!todo) return <p>Loading...</p>
return <p>{todo.description}</p>
}
streamName: stringgroupId: stringid?: stringuseStreamGroup<T>() returns { data: T[], event }useStreamItem<T>() returns { data: T | null | undefined, event }event is the subscription object used by useStreamEventHandler