# useTree

Provide stable structural query callbacks backed by the transport's conversation tree. These are thin `useCallback` wrappers around the tree's query methods. The hook does **not** re-render on tree changes — use [`useView`](https://ably.com/docs/ai-transport/api/react/use-view.md) when you want a reactive subscription. Reach for `useTree` when you need to query tree structure inside an event handler or a memoised computation without subscribing to every update.

This hook must be used within a [`TransportProvider`](https://ably.com/docs/ai-transport/api/react/providers.md#TransportProvider) or a [`ChatTransportProvider`](https://ably.com/docs/ai-transport/api/react/providers.md#ChatTransportProvider).

<Code>

#### React

```
import { useTree } from '@ably/ai-transport/react';

function BranchNav({ messageId }) {
  const { getSiblings, hasSiblings } = useTree();
  if (!hasSiblings(messageId)) return null;
  return <Arrows siblings={getSiblings(messageId)} />;
}
```
</Code>

## Parameters

<Table id='UseTreeProps'>

| Prop | Required | Description | Type |
| --- | --- | --- | --- |
| transport | Optional | Transport to read tree structure from. Defaults to the nearest provider when omitted. | `ClientTransport<TEvent, TMessage>` |

</Table>

## Returns

`TreeHandle<TMessage>`

<Table id='TreeHandle'>

| Property | Description | Type |
| --- | --- | --- |
| getSiblings | `(msgId: string) => TMessage[]`. Get every sibling message at a fork point, ordered chronologically by serial. | Function |
| hasSiblings | `(msgId: string) => boolean`. Whether a message has sibling alternatives. | Function |
| getNode | `(msgId: string) => MessageNode<TMessage> \| undefined`. Get a node by message ID. | Function |

</Table>

The returned callbacks are stable across renders (they are `useCallback`-wrapped), so they are safe to use as dependencies in `useEffect` or `useMemo` without triggering rerun loops.

## Example

<Code>

### React

```
import { useTree, useView } from '@ably/ai-transport/react';
import { useMemo } from 'react';

function ConversationStats() {
  const { messages } = useView();
  const { getSiblings } = useTree();

  const branchCount = useMemo(
    () => messages.reduce((total, m) => total + getSiblings(m.id).length, 0),
    [messages, getSiblings],
  );

  return <span>Total branches: {branchCount}</span>;
}
```
</Code>

## Related Topics

- [Providers](https://ably.com/docs/ai-transport/api/react/providers.md): TransportProvider and ChatTransportProvider for the AI Transport React integration.
- [useClientTransport](https://ably.com/docs/ai-transport/api/react/use-client-transport.md): Read a ClientTransport from the nearest TransportProvider in the AI Transport React integration.
- [useView](https://ably.com/docs/ai-transport/api/react/use-view.md): Subscribe to a paginated, branch-aware view of the AI Transport conversation tree from React.
- [useCreateView](https://ably.com/docs/ai-transport/api/react/use-create-view.md): Create an independent View over the AI Transport conversation tree from React, with its own branch selections and pagination.
- [useActiveTurns](https://ably.com/docs/ai-transport/api/react/use-active-turns.md): Subscribe to active turns on the AI Transport channel from React.
- [useAblyMessages](https://ably.com/docs/ai-transport/api/react/use-ably-messages.md): Subscribe to raw Ably InboundMessages on the AI Transport channel from React.
- [useChatTransport](https://ably.com/docs/ai-transport/api/react/use-chat-transport.md): Read a ChatTransport and its underlying ClientTransport from the nearest ChatTransportProvider in AI Transport.
- [useMessageSync](https://ably.com/docs/ai-transport/api/react/use-message-sync.md): Wire AI Transport message updates into Vercel useChat's message state from React.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.