Studio React hooks

A collection of convenient React hooks for working with the Studio.

Studio React hooks is a collection of React hooks the makes it more convenient to work with documents in custom workflows and custom input components. The hooks provide access to document states as well as ways to perform operations on documents.

All hooks can be required from the @sanity/react-hooks package.

Hooks

Gotcha

The hooks listed here are using a memory intensive local representation of the Sanity document and should not be used for more than a few documents at a time.

useEditState(id, type):Object

This hook provides information about a document's edit state.

Parameters

  • REQUIREDidstring

    The document id to get the edit state of.

  • REQUIREDtypestring

    The document type.

Returns

Returns an object that contains the draft document if available, and the published document if available.

null will be returned if the document is not yet available. The returned object has the following properties

  • draftnull | SanityDocument

    The draft version of the document.

  • publishednull | SanityDocument

    The published version of the document.

  • idstring

    The id of the document.

  • typestring

    The document type.

Example

import {useEditState} from '@sanity/react-hooks'

function MyComponent() {
  const {draft, published} = useEditState('someDocId', 'someDocType')
  if (published && draft) {
	  return <>This document is published and has edits</>
  }
  if (published) {
	  return <>This document is published and has no draft</>
  }
  if (draft) {
	  return <>This document has a draft</>
  }
  return <>This document does not exist</>
}

useValidation(id, type):Object

Returns the validation result for a document.

Parameters

  • REQUIREDidstring

    The document id to get the validation state of.

  • REQUIREDtypestring

    The document type.

Returns

Returns an object with the following properties:

  • isValidatingboolean

    Indicates if the document is currently being validated.

  • markersarray

    An array of markers with validation. A marker has the following properties:
    level: 'error' | 'warning'
    item.message: 'A validation message'

Example

import {useValidation} from '@sanity/react-hooks'

function MyComponent() {
  const {isValidating, markers} = useValidation('someDocId', 'someDocType')
  if (isValidating) {
	  return <>Validation in progress…</>
  }
  if (markers.length === 0) {
	  return <>This document is ✨perfect✨</>
  }
  return (
    <>
      This document has issues: 
      <ul>
        {markers.map(marker =>
          <li>{marker.level}: {marker.item.message}</li>
        )}
			</ul>
    </>
}

useSyncState(id, type):Object

This hook provides information about wether a document is currently being synced with the hosted data store or not. This hook is connected to a browser-local replica of the document. Every edit will go through this document and applied immediately. At regular intervals the local edits will be synchronized with the server, and this hook will return information about whether local changes is currently synchronized. This hook is useful if you want to know in your component whether there are local changes currently being synced or not.

Parameters

  • REQUIREDidstring

    The document id to get the sync state of.

  • REQUIREDtypestring

    The document type.

Returns

Returns an object with the following properties:

  • isSyncingboolean

    Indicates if the document is currently being synced.

Example

import {useSyncState} from '@sanity/react-hooks'

function MyComponent() {
  const {isSyncing} = useSyncState('someDocId', 'someDocType')
  return <>{isSyncing ? `Synchronizing…` : `Synchronized`}</>
}

useConnectionState(id, type):Object

This hook returns a value indicating whether the document is currently connected to the hosted data store. This react hook returns information about the connection status of the local document.

Parameters

  • REQUIREDidstring

    The document id to get the sync state of.

  • REQUIREDtypestring

    The document type.

Returns

Returns a string with one of the following values:

'connecting' | 'reconnecting' | 'connected'

It will return connecting if the doucment is currently being loaded, connected if the document is connected to the datastore or reconnecting if the connection is lost.

Example

import {useSyncState} from '@sanity/react-hooks'

function MyComponent() {
  const syncState = useSyncState('someDocId', 'someDocType')
  if (syncState === 'connecting') {
    return <>Loading document…</>
  }
  if (syncState === 'reconnecting') {
    return <>Connection lost. Reconnecting…</>
  }
  if (syncState === 'connected') {
    return <>Connected to data store…</>
  }
  return null
}

useDocumentOperation(id, type):Operations

This hook returns a set of operations for a given document. See the list of possible operations in the Operations section below. Each operation is an object that has a disabled and an execute method. The enabled property takes no parameters, and returns either false or a disabledReason string identifier. Each set of operation has its own set of disabledReason identifiers. Refer to the documentation for each operation below for more details.

Parameters

  • REQUIREDidstring

    The id of the document.

  • REQUIREDtypestring

    The schema type of the document.

Operations

Thee hook consists of the following operations:

publish

This will publish the document.

Returns

Returns an object with the following properties:

  • disabledfalse | string

    Returns one of the following values:


    false
    The operation is not disabled.

    LIVE_EDIT_ENABLED
    The document is in live-edit mode.

    ALREADY_PUBLISHED
    The document is already published and there are no draft edits.

    NO_CHANGES
    The document is not published or there are no unpublished changes.

  • executefunction

    Returns void

Example

This will only work in Studio for now.

import {useDocumentOperation} from '@sanity/react-hooks'

function MyComponent() {
  const {publish} = useDocumentOperation('someDocId', 'someDocType')
  return (
   <button
    type="button"
    disabled={!!publish.disabled}
    onClick={() => publish.execute()}
   >
     Publish
   </button>
  )
}

delete

Use this operation to delete a document. Also exported as del so it can be used as a valid JavaScript identifier.

Returns

Returns an object with the following properties:

  • disabledboolean | string

    Returns one of the following:

    false
    The document doesn't exist (yet).

    NOTHING_TO_DELETE

  • executefunction

    Returns void

Example

This will only work in Studio for now.

import {useDocumentOperation} from '@sanity/react-hooks'

function MyComponent() {
  const {del} = useDocumentOperation('someDocId', 'someDocType')
  return (
   <button
    type="button"
    disabled={!!del.disabled}
    onClick={() => del.execute()}
   >
     Delete
   </button>
  )
}

patch

Use this to make modifications (mutations) to a document. The execute function is synchronous and the modifications will be applied immediately.

Returns

Returns an object with the following properties:

  • disabledboolean

    Currently this always returns false.

  • executefunction

    A function that executes patches. Takes an array of patches to perform and returns void.

Example

import {useDocumentOperation} from '@sanity/react-hooks'

function MyComponent() {
  const {patch} = useDocumentOperation('someDocId', 'someDocType')
  return (
   <button
    type="button"
    disabled={!!patch.disabled}
    onClick={() => patch.execute([{set: {title: 'Hello'}}])}
   >
     Change title
   </button>
  )
}

discardChanges

This operation provides a way to discard the current unpublished changes (if any).

Returns

Returns an object with the following properties:

  • disabledfalse | string

    Returns one of the following values:

    false Changes can be discarded.

    NO_CHANGES No unpublished changes exist for the document.

    NOT_PUBLISHED The document is not currently published.

  • executefunction

    A function to run in order to discard current unpublished changes. Returns void.

unpublish

This operation unpublishes the document.

Returns

Returns an object with the following properties:

  • disabledfalse | string

    Returns one of the following values:

    false
    Changes can be discarded.

    LIVE_EDIT_ENABLED
    liveEdit is enabled for the document type.

    NOT_PUBLISHED
    The document is not currently published.

  • executefunction

    A function to run in order to unpublish the document. Returns void.

Example

import {useDocumentOperation} from '@sanity/react-hooks'

function MyComponent() {
  const {unpublish} = useDocumentOperation('someDocId', 'someDocType')
  return (
   <button
    type="button"
    disabled={!!unpublish.disabled}
    onClick={() => unpublish.execute()}
   >
     Unpublish
   </button>
  )
}

duplicate

This operation creates a duplicate of a document. It will create a new draft with the same contents as the current document. It will be disabled if the current document is empty (e.g. deleted or not yet created).

Returns

Returns an object with the following properties:

  • disabledfalse | string

    Returns one of the following:

    false
    The operation is not disabled.

    NOTHING_TO_DUPLICATE
    The operation is disabled because there current document is empty (e.g. deleted or not yet created)

  • execute(id)function

    A function to run in order to duplicate the document. Takes a document id as the first and only parameter. Returns void.

Example

import {useDocumentOperation} from '@sanity/react-hooks'
import uuid from '@sanity/uuid'

function MyComponent() {
  const {duplicate} = useDocumentOperation('someDocId', 'someDocType')

  const onClick = () => {
    const dupeId = uuid()
    duplicate.execute(dupeId)
  }

  return (
   <button
    type="button"
    disabled={Boolean(duplicate.disabled)}
    onClick={onClick}
   >
     Duplicate
   </button>
  )
}

restore

This operation makes it possible to restore a document to a previous revision.

Returns

Returns an object with the following properties:

  • disabledfalse

    Returns:

    false
    The operation is not disabled.

  • executefunction

    A function to run in order to restore the document. Returns void.

Was this article helpful?