Sanity Library Reference Docs
    Preparing search index...

    Function useApplyDocumentActions

    • Provides a stable callback function for applying one or more document actions.

      This hook wraps the core applyDocumentActions functionality from @sanity/sdk, integrating it with the React component lifecycle and SanityInstance. It allows you to apply actions generated by functions like createDocument, editDocument, deleteDocument, publishDocument, unpublishDocument, and discardDocument to documents.

      Features:

      • Applies one or multiple DocumentAction objects.
      • Supports optimistic updates: Local state reflects changes immediately.
      • Handles batching: Multiple actions passed together are sent as a single atomic transaction.
      • Integrates with the collaborative editing engine for conflict resolution and state synchronization.

      Returns <
          TDocumentType extends string = string,
          TDataset extends string = string,
          TProjectId extends string = string,
      >(
          action:
              | DocumentAction<TDocumentType, TDataset, TProjectId>
              | DocumentAction<TDocumentType, TDataset, TProjectId>[],
          options?: ApplyDocumentActionsOptions,
      ) => Promise<
          ActionsResult<
              SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
          >,
      >

      A stable callback function. When called with a single DocumentAction or an array of DocumentActions, it returns a promise that resolves to an ActionsResult. The ActionsResult contains information about the outcome, including optimistic results if applicable.

      This hook is a fundamental part of interacting with document state programmatically. It operates within the same unified pipeline as other document hooks like useDocument (for reading state) and useEditDocument (a higher-level hook specifically for edits).

      When multiple actions are provided in a single call, they are guaranteed to be submitted as a single transaction to Content Lake. This ensures atomicity for related operations (e.g., creating and publishing a document).

      import {
        publishDocument,
        unpublishDocument,
        useApplyDocumentActions,
        type DocumentHandle
      } from '@sanity/sdk-react'

      // Define props using the DocumentHandle type
      interface PublishControlsProps {
        doc: DocumentHandle
      }

      function PublishControls({doc}: PublishControlsProps) {
        const apply = useApplyDocumentActions()

        const handlePublish = () =>  apply(publishDocument(doc))
        const handleUnpublish = () => apply(unpublishDocument(doc))

        return (
          <>
            <button onClick={handlePublish}>Publish</button>
            <button onClick={handleUnpublish}>Unpublish</button>
          </>
        )
      }

      import {
        createDocument,
        publishDocument,
        createDocumentHandle,
        useApplyDocumentActions
      } from '@sanity/sdk-react'

      function CreateAndPublishButton({documentType}: {documentType: string}) {
        const apply = useApplyDocumentActions()

        const handleCreateAndPublish = () => {
          // Create a new handle inside the handler
          const newDocHandle = createDocumentHandle({ documentId: crypto.randomUUID(), documentType })

          // Apply multiple actions for the new handle as a single transaction
          apply([
            createDocument(newDocHandle),
            publishDocument(newDocHandle),
          ])
        }

        return (
          <button onClick={handleCreateAndPublish}>
            I'm feeling lucky
          </button>
        )
      }

      import {
        createDocument,
        createDocumentHandle,
        useApplyDocumentActions
      } from '@sanity/sdk-react'

      function CreateArticleButton() {
        const apply = useApplyDocumentActions()

        const handleCreateArticle = () => {
          const newDocHandle = createDocumentHandle({
            documentId: crypto.randomUUID(),
            documentType: 'article'
          })

          // Create document with initial values in one action
          apply(
            createDocument(newDocHandle, {
              title: 'New Article',
              author: 'John Doe',
              publishedAt: new Date().toISOString(),
            })
          )
        }

        return <button onClick={handleCreateArticle}>Create Article</button>
      }

    Settings

    Member Visibility