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

# useDocument

> The `useDocument` hook makes it simple to connect with realtime Firestore documents, even when paths are dynamic or depend on the ID of the current user. This hook is particularly useful in React applications where document paths depend on runtime values like user IDs or route parameters.

## Basic Usage

The simplest usage of `useDocument` is to provide a `DocumentReference` to the hook. This will fetch the document and return its data. The hook will also automatically update the component with the latest data whenever the document changes.

<CodeGroup>
  ```ts Web theme={null}
  import { useDocument } from '@firebridge/web'
  import { doc } from 'firebase/firestore'

  // Your local Firestore instance
  import firestore from '@/services/firestore'

  // Example use case: Fetching a user's profile
  const userProfile = useDocument<UserProfile>(
    doc(firestore, 'users', 'some-user-id'),
  )
  ```

  ```ts Native theme={null}
  import { useDocument } from '@firebridge/native'
  import firestore from '@react-native-firebase/firestore'

  // Example use case: Fetching a user's profile
  const userProfile = useDocument<UserProfile>(
    firestore.collection('users').doc('some-user-id'),
  )
  ```
</CodeGroup>

## Dynamic Paths

It's very common in Firebase applications to include the user's ID in the path to a document. This makes it simple to write Firestore security rules that restrict access to documents based on the user's ID. However, this also means that we need to know the user's ID before we can fetch the document.

To connect to a document at a dynamic path, we can provide a function instead of a `DocumentReference`. The function should return a `DocumentReference` and its first argument will be the user ID of the active user.

For example, here's how we can fetch the active user's own profile:

<CodeGroup>
  ```ts Web theme={null}
  // Example use case: Fetching the active user's own profile
  const ownUserProfile = useDocument<UserProfile>(uid =>
    doc(firestore, 'users', uid),
  )
  ```

  ```ts Native theme={null}
  // Example use case: Fetching the active user's own profile
  const ownUserProfile = useDocument<UserProfile>(uid =>
    firestore.collection('users').doc(uid),
  )
  ```
</CodeGroup>

## Custom Route Parameters

We can also include other string parameters in the document path, and ensure they exist before fetching the document. This is a common pattern in Firebase applications on React where document paths might depend on other dynamic values (e.g., route parameters). Firebridge makes it easy to manage these dependencies with a similar syntax to the `useEffect` hook.

For example, we might want to display a `User` and their current `Company` on the same page. In this case, the company document we want to connect to depends on the user document. This is a great use case for `useDocument`:

<CodeGroup>
  ```ts Web theme={null}
  // Let's connect to the user document first.
  const user = useDocument<User>(uid => doc(firestore, 'users', uid))
  const companyId = user?.companyId

  // Here, we'll pull in the company document.
  const company = useDocument<Company>(
    (_uid, c) => doc(firestore, 'companies', c),
    [companyId],
  )
  ```

  ```ts Native theme={null}
  // Let's connect to the user document first.
  const user = useDocument<User>(uid => firestore.collection('users').doc(uid))
  const companyId = user?.companyId

  // Here, we'll pull in the company document.
  const company = useDocument<Company>(
    (_uid, c) => firestore.collection('companies').doc(c),
    [companyId],
  )
  ```
</CodeGroup>

In this example, Firebridge will first create the user reference and fetch the user document. Once the user document is fetched, and their `companyId` is defined, Firebridge will create the company reference and fetch the company document.

Whether the user changes, or the company changes, or the user switches companies, Firebridge will automatically update the component with the latest data.