Sanity App SDK
    Preparing search index...

    Function useDocument

    Reads and subscribes to a document's realtime state, incorporating both local and remote changes.

    This hook comes in two main flavors to suit your needs:

    1. Type Inference (Recommended) - Automatically gets types from your Sanity schema
    2. Explicit Types - Manually specify types when needed

    useDocument is ideal for realtime editing interfaces where you need immediate feedback on changes. However, it can be resource-intensive since it maintains a realtime connection.

    For simpler cases where:

    • You only need to display content
    • Realtime updates aren't critical
    • You want better performance

    …consider using useDocumentProjection or useQuery instead. These hooks are more efficient for read-heavy applications.

    • The preferred way to use this hook when working with Sanity Typegen.

      Features:

      • Automatically infers document types from your schema
      • Provides type-safe access to documents and nested fields
      • Supports project/dataset-specific type inference
      • Works seamlessly with Typegen-generated types

      This hook will suspend while the document data is being fetched and loaded.

      When fetching a full document:

      • Returns the complete document object if it exists
      • Returns null if the document doesn't exist

      When fetching with a path:

      • Returns the value at the specified path if both the document and path exist
      • Returns undefined if either the document doesn't exist or the path doesn't exist in the document

      Type Parameters

      • TPath extends undefined | string = undefined
      • TDocumentType extends string = string
      • TDataset extends string = string
      • TProjectId extends string = string

      Parameters

      • options: {
            dataset?: TDataset;
            documentId: string;
            documentType: TDocumentType;
            path?: TPath;
            perspective?: ReleasePerspective | ClientPerspective;
            projectId?: TProjectId;
        }

        Configuration including documentId, documentType, and optionally:

        • path: To select a nested value (returns typed value at path)
        • projectId/dataset: For multi-project/dataset setups

      Returns TPath extends string
          ? {
              data: | undefined
              | JsonMatch<
                  SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
                  TPath<TPath>,
              >;
          }
          : {
              data: null
              | SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>;
          }

      The document state (or nested value if path provided).

      import {useDocument, type DocumentHandle} from '@sanity/sdk-react'

      interface ProductViewProps {
        doc: DocumentHandle<'product'> // Typegen infers product type
      }

      function ProductView({doc}: ProductViewProps) {
        const {data: product} = useDocument({...doc}) // Fully typed product
        return <h1>{product.title ?? 'Untitled'}</h1>
      }

      import {useDocument, type DocumentHandle} from '@sanity/sdk-react'

      interface ProductTitleProps {
        doc: DocumentHandle<'product'>
      }

      function ProductTitle({doc}: ProductTitleProps) {
        const {data: title} = useDocument({
          ...doc,
          path: 'title' // Returns just the title field
        })
        return <h1>{title ?? 'Untitled'}</h1>
      }

    • Use this version when:

      • You're not using Sanity Typegen
      • You need to manually specify document types
      • You're working with dynamic document types

      Key differences from Typegen version:

      • Requires manual type specification via TData
      • Returns TData | null for full documents
      • Returns TData | undefined for nested values

      This hook will suspend while the document data is being fetched.

      Type Parameters

      • TData

        The explicit type for the document or field

      • TPath extends string

        Optional path to a nested value

      Parameters

      • options: {
            dataset?: string;
            documentId: string;
            documentType: string;
            path?: TPath;
            perspective?: ReleasePerspective | ClientPerspective;
            projectId?: string;
        }

        Configuration including documentId and optionally:

        • path: To select a nested value
        • projectId/dataset: For multi-project/dataset setups

      Returns TPath extends string ? { data: undefined | TData } : { data: null | TData }

      The document state (or nested value if path provided)

      import {useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'

      interface Book extends SanityDocument {
        _type: 'book'
        title: string
        author: string
      }

      interface BookViewProps {
        doc: DocumentHandle
      }

      function BookView({doc}: BookViewProps) {
        const {data: book} = useDocument<Book>({...doc})
        return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
      }

      import {useDocument, type DocumentHandle} from '@sanity/sdk-react'

      interface BookTitleProps {
        doc: DocumentHandle
      }

      function BookTitle({doc}: BookTitleProps) {
        const {data: title} = useDocument<string>({...doc, path: 'title'})
        return <h1>{title ?? 'Untitled'}</h1>
      }

    Settings

    Member Visibility

    On This Page

    useDocument via Type Inference (Recommended)useDocument via Explicit Types