React hooks

AI Transport provides React hooks for building chat UIs. Generic hooks are available from @ably/ai-transport/react and work with any codec. Vercel-specific hooks are available from @ably/ai-transport/vercel/react.

Generic hooks

Import from the React entry point:

import {
  useClientTransport,
  useView,
  useCreateView,
  useSend,
  useEdit,
  useRegenerate,
  useTree,
  useActiveTurns,
  useAblyMessages,
} from '@ably/ai-transport/react'

useClientTransport

Create and memoize a ClientTransport instance. The transport is created on the first render and the same instance is returned on subsequent renders. The hook does not auto-close the transport on unmount; channel lifecycle is managed by the Ably provider. Call transport.close() explicitly if you need to tear down the transport independently of the channel lifecycle.

function useClientTransport(options: ClientTransportOptions): ClientTransport

See ClientTransportOptions for available options.

useView

Subscribe to a view and return the visible node list with pagination, navigation, and write operations. Accepts either a ClientTransport (uses its default view), a View directly, or null/undefined. Returns a ViewHandle that re-renders the component when the view updates.

function useView(
  source: ClientTransport | View | null | undefined,
  options?: UseViewOptions
): ViewHandle

UseViewOptions

When options are provided, the hook auto-loads the first page on mount.

ViewHandle

useCreateView

Create an additional view of the conversation tree. Returns a ViewHandle with the same interface as useView.

function useCreateView(transport: ClientTransport): ViewHandle

useSend

Return a stable send callback bound to the given view. Useful when you only need to send messages without subscribing to the full view.

function useSend(view: View): (messages: TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>

useEdit

Return a stable edit callback bound to the given view.

function useEdit(view: View): (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>

useRegenerate

Return a stable regenerate callback bound to the given view.

function useRegenerate(view: View): (messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>

useTree

Provide stable structural query callbacks backed by the transport's conversation tree. These are thin useCallback wrappers around the tree -- no local state or subscriptions. The hook does not re-render on tree changes; use useView for reactive updates.

function useTree(transport: ClientTransport): TreeHandle

TreeHandle

useActiveTurns

Subscribe to active turns on the channel. Returns a reactive Map keyed by client ID, where each value is a Set of turn IDs for that client. Re-renders when turns start or end.

function useActiveTurns(transport: ClientTransport): Map<string, Set<string>>

Use .size to check if any turns are active, .has(clientId) to check a specific client, and .get(clientId) to retrieve the set of turn IDs for a client. See concurrent turns for usage examples.

useAblyMessages

Subscribe to raw Ably messages on the transport's channel. Useful for building custom message handling outside the view abstraction.

function useAblyMessages(transport: ClientTransport): Ably.Message[]

Vercel hooks

Import from the Vercel React entry point:

import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react'

useChatTransport

Create a ChatTransport for use with Vercel's useChat hook. Accepts either a VercelClientTransportOptions object or an existing ClientTransport instance. Both forms accept an optional second argument for ChatTransportOptions.

function useChatTransport(options: VercelClientTransportOptions, chatOptions?: ChatTransportOptions): ChatTransport
function useChatTransport(transport: ClientTransport, chatOptions?: ChatTransportOptions): ChatTransport

When you pass VercelClientTransportOptions, the hook creates a new ClientTransport internally with the codec pre-bound to UIMessageCodec. When you pass an existing ClientTransport, it wraps that instance as a ChatTransport without creating a new transport.

Using options (creates transport internally):

const transport = useChatTransport({ channel })
const { messages } = useChat({ transport })

Using an existing ClientTransport:

const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId })
const chatTransport = useChatTransport(transport)
const { messages } = useChat({ transport: chatTransport })

Use the second form when you need direct access to the ClientTransport for features like active turn tracking or cancellation. See ChatTransportOptions for available options.

useMessageSync

Wire transport message updates into Vercel's useChat message state. Subscribes to the transport view's update event and replaces messages with the view's authoritative message list. Use this when you need Vercel's message array to reflect messages from other devices or browser tabs.

function useMessageSync(
  transport: ClientTransport | null | undefined,
  setMessages: (updater: (prev: UIMessage[]) => UIMessage[]) => void
): void

const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId })
const chatTransport = useChatTransport(transport)
const { messages, setMessages } = useChat({ transport: chatTransport })
useMessageSync(transport, setMessages)
// messages now includes messages from all devices