React Hooks
Meet some of the most important hooks from the React SDK package.
The Sanity App SDK comes with a range of hooks available for interacting with your content. A full reference is available for your perusal here:
While visiting every hook, type and component is beyond the scope of this article, a few of the most important hooks are briefly introduced below to give you a sense of how you'll be interacting with your Sanity content using the App SDK.
For the sake of legibility, assume that each example is invoked with a proper DocumentHandle, which is a valid combination of a document ID and document type, and an optional project ID and dataset name indicating the source of the document.
import {type DocumentHandle} from '@sanity/sdk-react'
const documentHandle: DocumentHandle = {
documentId: 'document-id',
documentType: 'book',
projectId: 'project-id',
dataset: 'production',
}
<OrderLink documentHandle={documentHandle} />- useDocument - Read and subscribe to a document in real time with local-first updates. When provided a path, it returns the corresponding field value.
import {type DocumentHandle, useDocument} from '@sanity/sdk-react'
export function OrderLink({documentHandle}: {documentHandle: DocumentHandle}) {
const {data: title} = useDocument({
...documentHandle,
path: 'title',
})
const {data: id} = useDocument({
...documentHandle,
path: '_id',
})
return (
<a href=`/order/${id}`>Order {title} today!</a>
)
}- useEditDocument - Mutate a document's values with optimistic, local-first updates. When provided a path, it returns a function for updating the corresponding field value.
import {type DocumentHandle, useDocument, useEditDocument} from '@sanity/sdk-react'
export function EditableTitle({documentHandle}: {documentHandle: DocumentHandle}) {
const {data: title} = useDocument<string>({
...documentHandle,
path: 'title',
})
const editTitle = useEditDocument<string>({
...documentHandle,
path: 'title'
})
function handleTitleChange(event: React.ChangeEvent<HTMLInputElement>) {
editTitle(event.currentTarget.value)
}
return (
<input type='text' value={title} onChange={handleTitleChange} />
)
}- useDocumentProjection - Used for efficient live data fetching. When provided a GROQ projection, it returns the projected values. These values are live and will update in sync with the document values in Content Lake!
import {type DocumentHandle, useDocumentProjection} from '@sanity/sdk-react'
export function BookDisplay({documentHandle}: {documentHandle: DocumentHandle}){
const {data: {title, coverImage, authors}, isPending} = useDocumentProjection({
...documentHandle,
projection: `{
title,
'coverImage': cover.asset->url,
'authors': array::join(authors[]->{'name': firstName + ' ' + lastName + ' '}.name, ', ')
}`,
})
return (
<article style={{ opacity: isPending ? 0.5 : 1}}>
<h2>{title}</h2>
<img src={coverImage} alt={title} />
<p>{authors}</p>
</article>
)
}- useDocuments and usePaginatedDocuments - Retrieves batches of documents (in the form of Document Handles), narrowed by optional filters, text matching and custom ordering.
import {useDocuments} from '@sanity/sdk-react'
export function DocumentList() {
const {count, data, hasMore,loadMore} = useDocuments({
documentType: 'post',
search: searchTerm,
batchSize: 10,
orderings: [{field: '_createdAt', direction: 'desc'}]
})
return (
<div>
Total documents: {count}
<ol>
{data.map((doc) => (
<li key={doc.documentId}>
<MyDocumentComponent doc={doc} />
</li>
))}
</ol>
{hasMore && <button onClick={loadMore}>Load More</button>}
</div>
)
}These are only a select handful of the most useful hooks provided by the SDK. To explore the entire set of hooks, components and types visit the React SDK reference docs. To see some example code in action, check out the SDK Explorer.
Was this page helpful?