Oryx provides a set of React hooks for managing chat state, message metadata, retrieval information, and streaming status. All hooks are exported from @contextualai/oryx-react.

useOryx

The primary hook for managing Oryx chat state and streaming lifecycle. Returns control functions and a probe object to pass into Oryx.Root.

const { probe, start, stop, states } = useOryx({ fetcher });

return <Oryx.Root probe={probe}>{/* ... */}</Oryx.Root>;

Parameters:

• fetcher — The fetcher function that handles SSE streaming to your backend.
  

  OryxChatFetcher

• extras — Optional extra data passed to the fetcher (e.g., agentId, auth tokens).
  

  TExtras

Returns:

• probe — The payload object to pass into Oryx.Root.
  

  OryxContextPayload

• start — Start a new chat request with the given prompt.
  

  (prompt: string) => void

• stop — Abort any in-flight streaming immediately.
  

  () => void

• states — A map of message IDs to their respective Oryx states.
  

  Record<string, OryxState>

useOryxStatus

Exposes the streaming status and error state for the current message.

This hook must be used within Oryx.Message.Agent to read the status of the current message properly.

const { isStreaming, error } = useOryxStatus();

• isStreaming — Whether the current message is actively streaming.
  

  boolean

• error — Error object if the streaming pipeline failed.
  

  OryxStreamingError | null

useOryxMessage

Returns identifiers and state for the current message.

This hook must be used within Oryx.Message.Agent to read the metadata of the current message properly.

const { messageId, requestId, conversationId, state } = useOryxMessage();

return (
  <ul>
    <li>Message ID: {messageId}</li>
    <li>Request ID: {requestId}</li>
    <li>Conversation ID: {conversationId}</li>
  </ul>
);

• messageId — Unique identifier for this message turn.
  

  string

• requestId — Upstream request ID from the API.
  

  string | null

• conversationId — Conversation thread ID, persisted across turns.
  

  string | null

• state — Full state object with message, status, and retrieval information.
  

  OryxState

useOryxRetrievals

Returns the list of retrievals for the current message.

This hook must be used within Oryx.Message.Agent to access retrievals properly.

const { retrievals } = useOryxRetrievals();

• retrievals — Array of retrieval items for the current message.
  

  OryxRetrieval[]

useOryxRetrievalItem

Returns the retrieval data for the current item.

This hook must be used within Oryx.Retrievals.List or Oryx.Retrievals.RawList.

const { retrieval } = useOryxRetrievalItem();

• retrieval — The retrieval item data including contentId, number, type, name, and snippet.
  

  OryxRetrieval

useOryxContext

Low-level hook to access the root Oryx context directly. Useful for building custom integrations outside the standard component tree.

Prefer using useOryx for standard use cases. This hook is for advanced scenarios only, where you want to avoid passing helper functions deeply into the component tree, or want to access all states directly.

const { states, start, stop } = useOryxContext();

• states — A map of message IDs to their respective Oryx states.
  

  Record<string, OryxState>

• start — Start a new chat request with the given prompt.
  

  (prompt: string) => void

• stop — Stop all ongoing streaming requests.
  

  () => void