useEditDocument

You've seen how simple it is to create performant, real-time lists of documents. Prepare to be amazed at how simple it is to edit them.

While the API in this lesson may look simple, what it's doing under the hood is anything but. Edits are optimistically written to an in-browser cache. When editing a published document, a new draft is immediately invoked, behavior which the Sanity Studio performs but has been difficult to replicate with Sanity Client alone.

The fetch from useDocument in the previous lesson provided us with real-time document values, now you can create form components which will update those values.

First let's create a control to update the value of the sentiment field with a selection of radio buttons.

import { DocumentHandle, useEditDocument } from "@sanity/sdk-react"
import { Radio, Text, Inline, Stack } from "@sanity/ui"

type SentimentProps = {
  value: string
  handle: DocumentHandle
}

const SENTIMENTS = ["Positive", "Neutral", "Negative"]

export function Sentiment({ value, handle }: SentimentProps) {
  const editSentiment = useEditDocument({ ...handle, path: "sentiment" })

  return (
    <Stack space={3}>
      <Text weight="medium">Sentiment</Text>
      <Inline space={3}>
        {SENTIMENTS.map((sentiment) => (
          <Inline key={sentiment} as="label" space={1} htmlFor={sentiment}>
            <Radio
              id={sentiment}
              checked={value === sentiment.toLowerCase()}
              onChange={(e) => editSentiment(e.currentTarget.value)}
              name="sentiment"
              value={sentiment.toLowerCase()}
            />
            <Text>{sentiment}</Text>
          </Inline>
        ))}
      </Inline>
    </Stack>
  )
}

Notice how this component uses useEditDocument to only modify a specific path in the document. This means any value passed into the editSentiment function will be automatically written to that path in the document.

{/* In the next lessons... */}
<Sentiment value={sentiment} handle={selectedFeedback} />

You can now click the radio buttons on any selected document, and the edits will take place in real time.

Open the same document side-by-side in your app and Sanity Studio to see how the changes are reflected to both documents. As well as noting how drafts are automatically invoked when making edits to published documents.

The notes field in our feedback schema is for authors to add some helpful details for other team members to read.

import { type DocumentHandle, useEditDocument } from "@sanity/sdk-react"
import { Stack, Text, TextArea } from "@sanity/ui"

type NotesProps = {
  value: string
  handle: DocumentHandle
}

export function Notes({ value, handle }: NotesProps) {
  const editNotes = useEditDocument({ ...handle, path: "notes" })

  return (
    <Stack space={3}>
      <Text weight="medium">Reviewer Notes</Text>
      <TextArea
        value={value}
        onChange={(e) => editNotes(e.currentTarget.value)}
        placeholder="Add your notes about this feedback..."
        rows={3}
      />
    </Stack>
  )
}

This component is quite similar to the Sentiment component before, where editDocument is configured with a pre-set path, and the TextArea input writes changes to it.

<Notes value={notes} handle={selectedFeedback} />

Once again, try writing into the text field, and watch the same document in Sanity Studio update almost immediately after.

Open to enlarge image

You're now able to make edits to documents, but they're all left in a draft state. So our authors can't commit their changes.

You'll setup document actions in the next lesson to finish the work.