App SDK

Fetching and handling content

Learn about the central concepts and hooks for pulling content from your Sanity project into your custom app.

The App SDK provides a number of React hooks for interacting with your Sanity content. In this article we'll look at four specific hooks – useDocuments, useDocument, useDocumentProjection, and useEditDocument – and explore how they fill different needs within a single custom app.

Loading complex previews with useDocuments and useDocumentProjection

In this section we'll fetch a list of movie documents and display them in a nice grid of card elements, each containing some info and a visual.

A grid layout of card elements displaying movie poster images along with title and top billed cast

Preparing our list view

The first thing we want to do is fetch a list of document handles for all the movies we want to display. Document handles are minimalist objects that contain just the necessary amount of information to identify a document in your Content Lake.

For this task we'll use the useDocuments hook.

👉 Create a new component in your src folder named PreviewGrid.tsx and add the following code to it:

This will set up a pretty grid layout for our movie previews. Note that we wrap each <MoviePreview /> component in individual React.Suspense />-wrappers. You can read more about how the App SDK employs Suspense to ensure smooth data fetching in this article.

Let's move on to the <MoviePreview />-component. This component will receive a documentHandle prop, and use that information to fetch the relevant data from the Content Lake.

Movie preview component with useDocumentProjection

The useDocuments hook is very handy for fetching document handles for a bunch of documents, but it only contains enough data to identify the relevant document. For more complex data fetching, the useDocumentProjection hook comes in handy. Note that the useDocumentProjection hook is not recommended for real-time editing. A better alternative for those situations is discussed in the next section.

Examining the schema for the movie document type, we see that it contains a number of fields. For our purposes, we'll focus on the following:

  • A title field of type string
  • A poster field of type image
  • A castMembers field which is an array of references to a person type which has a name.
Shows a studio editor with the document inspection popover open
You can inspect the schema by clicking the ellipsis menu in the top of the studio editor pane

We want to display the title along with a poster image and the names of the first two listed cast members, which means we'll need content from three different documents and an asset. Sounds like a job for GROQ!

Using a GROQ projection, we can easily drill into the referenced documents and fetch exactly the structure we need.

That should be all we need to display our movie cards.

👉 Create a new component named MoviePreview.tsx in your src folder, and paste the following code into it.

The final step we need to do is update our src/App.tsx to display our shiny new movie grid.

👉 Edit your src/App.tsx to import and render our grid component:

You should now see each preview card updated with the actual information we wanted to display. Go ahead and change the title of any movie document in the corresponding studio to see the preview card live update as you make changes.

Shows a list of movie preview cards complete with posters, titles, and top billed cast

Make real-time edits with useEditDocument

useDocumentProjection is great, but it's not suitable for situations where you need down to the millisecond responsive content updates for, e.g., live collaborative editing. Let's expore this by making our movie titles editable with useEditDocument.

👉 Create a new file in src/ named TitleEditor.tsx and paste the following code:

In this component we first use the useDocument hook to fetch the current value of title, and then we use useEditDocument to create a real-time edit function that is called on every change event from the input element.

Plural or singular? It makes a difference.

👉 Remember to also update MoviePreview.tsx:

You should be able to click any movie title and edit it. Open up your studio to observe the changes happening to the document in real time.

Shows our grid app side by side with Sanity Studio

Was this page helpful?