> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Connections

> Open and keep a MeshAgent room document in sync from React or Flutter.

Use a document connection helper when your UI needs a live room document.

This sits one level below a room connection: first connect to the room, then open the document you want to render or edit.

## React

Use `useDocumentConnection` from `@meshagent/meshagent-react`:

```tsx theme={null}
import { useDocumentConnection } from "@meshagent/meshagent-react";

export function DocumentView({ room }: { room: any }) {
  const { document, error, loading } = useDocumentConnection({
    room,
    path: "/notes/thread.thread",
  });

  if (loading) return <div>Loading document...</div>;
  if (error) return <div>Error: {String(error)}</div>;
  if (!document) return <div>No document</div>;

  return <div>Connected to document {document.id}</div>;
}
```

## Flutter

Use `DocumentConnectionScope` from `meshagent_flutter`:

```dart theme={null}
import 'package:flutter/widgets.dart';
import 'package:meshagent/meshagent.dart';
import 'package:meshagent_flutter/meshagent_flutter.dart';

class SampleWidget extends StatelessWidget {
  const SampleWidget({
    super.key,
    required this.room,
    required this.path,
  });

  final RoomClient room;
  final String path;

  @override
  Widget build(BuildContext context) {
    return DocumentConnectionScope(
      path: path,
      room: room,
      builder: (context, document, error) {
        if (error != null) {
          return Text('Error: $error');
        }

        if (document == null) {
          return Text('Loading...');
        }

        return Text('Document loaded: ${document.id}');
      },
    );
  }
}
```

## What these helpers do

* open the document from an existing `RoomClient`
* keep the connection alive while your component or widget is mounted
* surface loading or error state back into the UI
* close the document connection when the UI goes away

## When to use this

Use a document connection when your app needs a live, room-backed document surface such as:

* shared notes
* thread documents
* structured room content

For the lower-level runtime model behind these helpers, see [Sync / Documents](../room_api/sync).