sanity-plugin-utils

Handy hooks and clever components for Sanity Studio v3.

Installation

npm install --save sanity-plugin-utils

or

yarn add sanity-plugin-utils

Usage

useListeningQuery()

Sanity's real-time APIs power excellent editorial experiences. Your plugins should respond to other users collaborating on documents in real time. This hook is a convenient way to perform a GROQ query that responds to changes, along with built-in loading and error states.

The data variable will be constantly updated as changes are made to the data returned by your query. You can also pass in initial data so that it is set in the first render.

import {useListeningQuery} from 'sanity-plugin-utils'

export default function DocumentList() {
  const {data, loading, error} = useListeningQuery<SanityDocument[]>(`*[_type == $type]`, {
    params: {type: 'pet'},
    initialValue: [],
  })

  if (loading) {
    return <Spinner />
  }

  if (error) {
    return <Feedback tone="critical">{error}</Feedback>
  }

  return (
    <Stack>
      {data?.length > 0 ? (
        data.map((pet) => <Card key={pet._id}>{pet.title}</Card>)
      ) : (
        <Feedback>No Pets found</Feedback>
      )}
    </Stack>
  )
}

useProjectUsers()

Hook for getting extended details on all Users in the project. Such as name.

import {useProjectUsers} from 'sanity-plugin-utils'

export default function DocumentList() {
  const users = useProjectUsers({apiVersion: `2023-01-01`})

  return (
    <Stack>
      {users?.length > 0 ? (
        users.map((user) => (
          <Profile key={user.id} {...user}>
        ))
      ) : (
        <Spinner>
      )}
    </Stack>
  )
}

useOpenInNewPane()

Returns a function that will open a document in a new view pane, alongside the current view pane

import {useOpenInNewPane} from 'sanity-plugin-utils'

export default function SidePetOpener(pet: SanityDocument) {
  const openInNewPane = useOpenInNewPane(pet._id, pet._type)

  return (
    <Button onClick={() => openInNewPane()}>
      {pet.title}
    </Button>
  )
}

useImageUrlBuilder()

Returns an image URL builder configured with the current workspace's Project ID and Dataset.

Useful if you have many images in the one component.

import {useImageUrlBuilder} from 'sanity-plugin-utils'

export default function PetPics(pet: SanityDocument) {
  const builder = useImageUrlBuilder({apiVersion: `2023-01-01`})

  return (
    <ul>
      {pet.pics.map((pic) => (
        <li key={pic._key}>
          <img src={builder.source(pic).width(200).height(200).url()} alt={pic.altText} />
        </li>
      ))}
    </ul>
  )
}

useImageUrlBuilderImage()

As above, but pre-configured with an image source.

Useful if you only have one image in your component.

import {useImageUrlBuilderImage} from 'sanity-plugin-utils'

export default function PetPic(pet: SanityDocument) {
  const image = useImageUrlBuilderImage(pet.image, {apiVersion: `2023-01-01`})

  return <img src={image.width(200).height(200).url()} alt={pet.name} />
}

Feedback

Component for consistently displaying feedback in a card with a title, text and an icon.

import {Feedback, useListeningQuery} from 'sanity-plugin-utils'

export default function DocumentList() {
  const {data, loading, error} = useListeningQuery(`*[_type == "task" && !complete]`)

  if (loading) {
    return <Feedback tone="primary" title="Please hold" description="Fetching tasks..." />
  }

  if (error) {
    return (
      <Feedback tone="critical" title="There was an error" description="Please try again later" />
    )
  }

  return data?.length > 0 ? (
    <Feedback tone="caution" title="There are unfinished tasks" description="Please get to work" />
  ) : (
    <Feedback tone="success" title="You're all done" description="You should feel accomplished" />
  )
}

Table, Row and Cell

These components are all @sanity/ui Card's but with their HTML DOM elements and CSS updated to output and behave like tables.

import {Table, Row, Cell} from 'sanity-plugin-utils'

export default function Report(documents) {
  return (
    <Table>
      <thead>
        <Row>
          <Cell>
            <Text>Name</Text>
          </Cell>
          <Cell>
            <Text>Price</Text>
          </Cell>
        </Row>
      </thead>
      <tbody>
        {documents.map((doc) => (
          <Row key={doc._id}>
            <Cell>
              <Text>{doc.title}</Text>
            </Cell>
            <Cell tone={doc.inStock ? `caution` : `primary`}>
              <Text>{doc.price}</Text>
            </Cell>
          </Row>
        ))}
      </tbody>
    </Table>
  )
}

UserSelectMenu

A Menu component for searching and interacting with users. Requires Users to be passed into the component.

import {UserSelectMenu} from 'sanity-plugin-utils'

export default function Report() {
  const users = useProjectUsers({apiVersion: `2023-01-01`})
  const [selectedUsers, setSelectedUsers] = useState([])
  
  return (
    <UserSelectMenu
      userList={users}
      value={selectedUsers}
      onAdd={(id) => selectedUsers((current) => [...current, id])}
      onRemove={(id) => setSelectedUsers((current) => current.filter((id) => id !== id))}
      onClear={() => setSelectedUsers([])}
    >
  )
}

License

MIT © Simeon Griggs See LICENSE

License

MIT © Simeon Griggs

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.