> This page location: Realtime > SDKs > TypeScript > React
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: Reference for the Realtime React bindings, @neon/realtime-react, covering RealtimeProvider, the useLiveQuery hook and its result, and useRealtimeClient.

# TypeScript SDK: React

Bind live queries to React components with @neon/realtime-react

Last updated: 2026-11-18

Import the React bindings from `@neon/realtime-react`. They run in your React frontend: [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider) shares one client, [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery) subscribes a component to a sealed query, and [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript/react#react-userealtimeclient) returns the shared client. They're taught in the [React section](https://neon.com/docs/realtime/guides/reactivity#react) of the reactivity guide.

## API reference

**Import specifier** `@neon/realtime-react`

### Symbols

| Symbol | Kind | Summary |
| - | - | - |
| [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider) | Function | Provide one shared Realtime client to descendant [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery) and [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript/react#react-userealtimeclient) hooks. Create the client once for the browser application. The provider does not fetch sealed queries or close the client when it unmounts. |
| [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery) | Function | Subscribe to a sealed query and expose its materialized snapshot to React. The hook owns subscription cleanup. |
| [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript/react#react-userealtimeclient) | Function | Read the shared Realtime client from the nearest [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider). Use it alongside [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery) when a component needs the client itself: to pass it to `realtimeCollectionOptions()` from `@neon/realtime-tanstack`, or to call `subscribe()` with a sealed query directly. Subscriptions opened through `subscribe()` are not owned by React, so call `unsubscribe()` when they are no longer needed. |
| [`RealtimeProviderProps`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeproviderprops) | Interface | Props accepted by [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider). |
| [`UseLiveQueryOptions`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequeryoptions) | Interface | Options for [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery). |
| [`UseLiveQueryResult`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequeryresult) | Type alias | React-facing snapshot and lower-level utilities returned by `useLiveQuery()`. |
| [`UseLiveQueryUtils`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequeryutils) | Type alias | Stable imperative access to the hook's underlying materialized subscription. Cleanup remains owned by React, so `unsubscribe()` is intentionally omitted. |

### RealtimeProvider

```ts
function RealtimeProvider(props: RealtimeProviderProps): ReactElement
```

Provide one shared Realtime client to descendant [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery) and
[`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript/react#react-userealtimeclient) hooks.

Create the client once for the browser application. The provider does not
fetch sealed queries or close the client when it unmounts.

**Returns:** A context provider for Realtime hooks.

#### Parameters

| Name | Type | Description |
| - | - | - |
| `props` | `RealtimeProviderProps` | Shared client and descendant React tree. |

#### Returns

`ReactElement`

### useLiveQuery

```ts
function useLiveQuery<Row>(query: SealedLiveQuery<Row>, options: UseLiveQueryOptions<NoInferCompat<Row>> = {}): UseLiveQueryResult<Row>
```

Subscribe to a sealed query and expose its materialized snapshot to
React. The hook owns subscription cleanup.

**Returns:** The current rows and lifecycle state plus stable subscription
utilities.

**Throws:** If used outside a [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider).

#### Type parameters

| Name | Default | Description |
| - | - | - |
| `Row` | | Row inferred from the query. |

#### Parameters

| Name | Type | Description |
| - | - | - |
| `query` | `SealedLiveQuery<Row>` | Capability obtained from the application backend. |
| `options` | `UseLiveQueryOptions<NoInferCompat<Row>>` | Optional preloaded rows and capability-refresh callback. |

#### Returns

`UseLiveQueryResult<Row>`

### useRealtimeClient

```ts
function useRealtimeClient(): RealtimeClient
```

Read the shared Realtime client from the nearest [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider).

Use it alongside [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery) when a component needs the client
itself: to pass it to `realtimeCollectionOptions()` from
`@neon/realtime-tanstack`, or to call `subscribe()` with a sealed query
directly. Subscriptions opened through `subscribe()` are not owned by React,
so call `unsubscribe()` when they are no longer needed.

**Returns:** The client passed to the nearest provider.

**Throws:** If used outside a [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider).

**Example**

```tsx
import type { SealedLiveQuery } from "@neon/realtime/client";
import { useRealtimeClient } from "@neon/realtime-react";
import { realtimeCollectionOptions } from "@neon/realtime-tanstack";
import { createCollection } from "@tanstack/db";
import { useMemo } from "react";

interface Todo {
  id: string;
  title: string;
}

function useTodos(query: SealedLiveQuery<Todo>) {
  const client = useRealtimeClient();
  return useMemo(
    () =>
      createCollection(realtimeCollectionOptions({
        client,
        query,
        getKey: (todo) => todo.id,
      })),
    [client, query],
  );
}
```

#### Returns

`RealtimeClient`

### RealtimeProviderProps

```ts
interface RealtimeProviderProps
```

Props accepted by [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript/react#react-realtimeprovider).

#### Members

| Name | Type | Description |
| - | - | - |
| `children` | `readonly ReactNode` | React subtree that may call [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery) or [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript/react#react-userealtimeclient). |
| `client` | `readonly RealtimeClient` | Shared browser client made available to descendant hooks. |

### UseLiveQueryOptions

```ts
interface UseLiveQueryOptions<Row>
```

Options for [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript/react#react-uselivequery).

#### Members

| Name | Type | Description |
| - | - | - |
| `initialData?` | `readonly Row[]` | Decoded rows exposed immediately, including during server rendering. Restore values changed by transport serialization before passing them here. |
| `refreshQuery?` | `readonly () => Promise<SealedLiveQuery<Row>>` | Obtain a replacement capability for the same exact query before expiry. Transient failures are retried while the current capability remains valid. |

### UseLiveQueryResult

```ts
type UseLiveQueryResult<Row> = LiveQuerySnapshot<Row> & { readonly utils: UseLiveQueryUtils<Row> }
```

React-facing snapshot and lower-level utilities returned by `useLiveQuery()`.

### UseLiveQueryUtils

```ts
type UseLiveQueryUtils<Row> = Omit<MaterializedLiveQuerySubscription<Row>, "unsubscribe">
```

Stable imperative access to the hook's underlying materialized subscription.

Cleanup remains owned by React, so `unsubscribe()` is intentionally omitted.

---

## Related docs (TypeScript)

- [Backend](https://neon.com/docs/realtime/sdks/typescript/backend)
- [Client](https://neon.com/docs/realtime/sdks/typescript/client)
- [TanStack DB](https://neon.com/docs/realtime/sdks/typescript/tanstack-db)
- [Drizzle](https://neon.com/docs/realtime/sdks/typescript/drizzle)
- [Kysely](https://neon.com/docs/realtime/sdks/typescript/kysely)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/realtime/sdks/typescript/react"}` to https://feedback.neon.tech/ (no auth required).
