Custom document badges

A document badge is a small UI component that indicates the status of a document. It currently appears in the Studio next to the toolbar actions. The default set of document badges currently shows draft and published status.

Depending on how you're implementing your workflows, you may want to control the badges that are displayed here. For example, if you have a workflow that includes reviewing you want to display pending review as a badge here.

Learn more about creating custom workflows →

More details in the document badge reference documentation →

In order to implement your own custom badge you need to perform two steps:

1. Create a function that defines the badge
2. Register the badge and resolve which badges should be displayed when.

Here's how:

export function HelloWorldBadge(props) {
  return {
    label: 'Hello world',
		title: 'Hello I am a custom document badge',
    color: "success"
  }
} 

The document badge component above can be added to your Studio by making a custom implementation of the part part:@sanity/base/document-badges/resolver by creating a file named resolveDocumentBadges.js and adding it to your Studio's sanity.json's parts section:

// sanity.json
//...

"parts": [
  //...
  {
    "implements": "part:@sanity/base/document-badges/resolver",
	  "path": "resolveDocumentBadges.js"
  }
]

The document badge resolver provides you with a central place to make decisions about the collection of badges enabled for a given document state. For example, this is where you can decide on the order of which the badges will appear.

Your implementation of the part:@sanity/base/document-badges/resolver must have a default export that is a function that is called with an argument with information about the document, and returns an array of enabled badges. To disable all the default badges, you can do:

// resolveDocumentBadges.js

export default function resolveDocumentBadges(props) {
  return []
}

But this would not be very useful, so let's instead add our HelloWorldBadge to the list of default document badges:

// resolveDocumentBadges.js

// import the default document badge resolver
import defaultResolve from 'part:@sanity/base/document-badges'

import {HelloWorldBadge} from './HelloWorldBadge'

export default function resolveDocumentBadges(props) {
  return [...defaultResolve(props), HelloWorldBadge]
}

When editing a document in the studio next time, you should see your badge appear in the tool

bar when editing a document: