Sanity App SDK
    Preparing search index...

    Function useEditDocument

    Provides a stable function to apply edits to a document or a specific path within it.

    This hook simplifies editing documents by automatically:

    • Comparing the current and next states to determine the minimal set of set and unset operations required for the update via editDocument.
    • Handling both full document updates and specific path updates.
    • Supporting functional updates (e.g., edit(prev => ({...prev, title: 'New'}))).
    • Integrating with the active SanityInstance context.
    • Utilizing useApplyDocumentActions internally for optimistic updates and transaction handling.

    It offers several overloads for flexibility:

    1. Typegen (Full Document): Edit the entire document, inferring types from your schema.
    2. Typegen (Specific Path): Edit a specific field, inferring types.
    3. Explicit Type (Full Document): Edit the entire document with a manually specified type.
    4. Explicit Type (Specific Path): Edit a specific field with a manually specified type.

    This hook relies on the document state being loaded. If the document is not yet available (e.g., during initial load), the component using this hook will suspend.

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

    // Assume 'product' schema has a 'title' field (string)
    interface ProductEditorProps {
      productHandle: DocumentHandle<'product'> // Typegen infers 'product' type
    }

    function ProductEditor({ productHandle }: ProductEditorProps) {
      // Fetch the document to display its current state (optional)
      const {data: product} = useDocument(productHandle);
      // Get the edit function for the full document
      const editProduct = useEditDocument(productHandle);

      // Use useCallback for stable event handlers
      const handleTitleChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
        const newTitle = event.target.value;
        // Use the functional updater for safe partial updates
        editProduct(prev => ({
          ...prev,
          title: newTitle,
        })).
      }, [editProduct]);

      return (
        <div>
          <label>
            Product Title:
            <input
              type="text"
              value={product?.title ?? ''}
              onChange={handleTitleChange}
            />
          </label>
        </div>
      );
    }

    import React, { useCallback } from 'react';
    import {useEditDocument, useDocument, type DocumentHandle, type DocumentOptions} from '@sanity/sdk-react'

    // Assume 'product' schema has a 'price' field (number)
    interface ProductPriceEditorProps {
      productHandle: DocumentHandle<'product'>;
    }

    function ProductPriceEditor({ productHandle }: ProductPriceEditorProps) {
      // Construct DocumentOptions internally, combining the handle and a hardcoded path
      const priceOptions {
        ...productHandle,
        path: 'price', // Hardcode the path to edit
      };

      // Fetch the current price to display it
      const {data: currentPrice} = useDocument(priceOptions);
      // Get the edit function for the specific path 'price'
      const editPrice = useEditDocument(priceOptions);

      const handleSetFixedPrice = useCallback(() => {
        // Update the price directly to a hardcoded value
        editPrice(99.99)
      }, [editPrice]);

      return (
        <div>
          <p>Current Price: {currentPrice}</p>
          <button onClick={handleSetFixedPrice}>
            Set Price to $99.99
          </button>
        </div>
      );
    }
    

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

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

    interface BookEditorProps {
      bookHandle: DocumentHandle // No documentType needed if providing TData
    }

    function BookEditor({ bookHandle }: BookEditorProps) {
      const {data: book} = useDocument<Book>(bookHandle);
      // Provide the explicit type <Book>
      const editBook = useEditDocument<Book>(bookHandle);

      const handleAuthorChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
        const newAuthor = event.target.value;
        editBook(prev => ({
          ...prev,
          author: newAuthor
        }))
      }, [editBook]);

      return (
         <div>
          <label>
            Book Author:
            <input
              type="text"
              value={book?.author ?? ''}
              onChange={handleAuthorChange}
            />
          </label>
        </div>
      );
    }
    

    import React, { useCallback } from 'react';
    import {useEditDocument, useDocument, type DocumentHandle, type DocumentOptions} from '@sanity/sdk-react'

    // Assume 'book' has 'author.name' (string)
    interface AuthorNameEditorProps {
      bookHandle: DocumentHandle; // No documentType needed if providing TData for path
    }

    function AuthorNameEditor({ bookHandle }: AuthorNameEditorProps) {*
      // Fetch current value
      const {data: currentName} = useDocument<string>({...bookHandle, path: 'author.name'});
      // Provide the explicit type <string> for the path's value
      const editAuthorName = useEditDocument<string>({...bookHandle, path: 'author.name'});

      const handleUpdate = useCallback(() => {
        // Update with a hardcoded string directly
        editAuthorName('Jane Doe')
      }, [editAuthorName]);

      return (
        <div>
          <p>Current Author Name: {currentName}</p>
          <button onClick={handleUpdate} disabled={currentName === undefined}>
            Set Author Name to Jane Doe
          </button>
        </div>
      );
    }

    • Edit an entire document, relying on Typegen for the type.

      Type Parameters

      • TDocumentType extends string = string
      • TDataset extends string = string
      • TProjectId extends string = string

      Parameters

      Returns (
          nextValue: Updater<
              SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
          >,
      ) => Promise<
          ActionsResult<
              SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
          >,
      >

      A stable function to update the document state. Accepts either the new document state or an updater function (currentValue) => nextValue. Returns a promise resolving to the ActionsResult.

    • Edit a specific path within a document, relying on Typegen for the type.

      Type Parameters

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

      Parameters

      Returns (
          nextValue: Updater<
              JsonMatch<
                  SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
                  TPath,
              >,
          >,
      ) => Promise<
          ActionsResult<
              SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
          >,
      >

      A stable function to update the value at the specified path. Accepts either the new value or an updater function (currentValue) => nextValue. Returns a promise resolving to the ActionsResult.

    • Edit an entire document with an explicit type TData.

      Type Parameters

      • TData

      Parameters

      • options: __type<undefined>

        Document options including documentId and optionally projectId/dataset.

      Returns (nextValue: Updater<TData>) => Promise<ActionsResult<_SanityDocument>>

      A stable function to update the document state. Accepts either the new document state (TData) or an updater function (currentValue: TData) => nextValue: TData. Returns a promise resolving to the ActionsResult.

    • Edit a specific path within a document with an explicit type TData.

      Type Parameters

      • TData

      Parameters

      • options: __type<string>

        Document options including documentId, path, and optionally projectId/dataset.

      Returns (nextValue: Updater<TData>) => Promise<ActionsResult<_SanityDocument>>

      A stable function to update the value at the specified path. Accepts either the new value (TData) or an updater function (currentValue: TData) => nextValue: TData. Returns a promise resolving to the ActionsResult.

    Settings

    Member Visibility