Document Actions API

Add custom operations on documents.

You can use the Document Actions API for Sanity Studio to customize and control operations that can be done to documents. When you create a custom action it will be available in the actions menu in the document editor. You create custom actions by returning a Document action component to an action resolver that you implement from sanity.json.

Learn how to create custom workflows with the Document Actions API.

Use Document actions to build custom workflows

Document Action resolver

The document action resolver provides you with a central place to make decisions about the collection of actions enabled for a given document state.

For example, this is where you can decide on the order of which the action components will appear. The first item in the array will appear as the primary action, that is, the blue button. The following items will populate the menu with the next on the top, and the last item on the bottom.

Properties

Example

// resolveDocumentActions.js

// import the default document actions
import defaultResolve from 'part:@sanity/base/document-actions'

import {PromoteProjectOnTwitter} from './PromoteProjectOnTwitter'

export default function resolveDocumentActions(props) {
  if (props.type !== "project") {
    return defaultResolve(props)
  }
  // If the document is of the type “project”, return the extra action
  return [...defaultResolve(props), PromoteProjectOnTwitter]
}

Document Action components

This table describes the values a document action component recieves as properties:

Properties

  • typestring

    The schema type of the current document.


  • draftSanityDocument

    The draft document (e.g. unpublished changes) if any.

    Returns null if there are no unpublished changes.

  • publishedSanityDocument

    The version of the document that is currently published (if any).

    Returns null if the document isn't published.

  • onCompletefunction

    A callback function that the action components must call to signal that the action has completed

Document Action description

Every Document Action component must return either null or an action description object. An action description describes the action state that can be used to render action components in different render contexts (e.g. in a toolbar, as a menu item, etc.). This table describes the different properties of an action description object.

  • REQUIREDlabelstring

    This is the action label. If the action is displayed as a button, this is typically what becomes the button label.

  • REQUIREDonHandlevoid

    This allows the action component to specify a function that gets called when the user wants the action to happen (e.g. the user clicked the button or pressed the keyboard shortcut combination). The implementation of the onHandle must either make sure to start the dialog flow or to execute the operation immediately.

  • iconReact Element

    In render contexts where it makes sense to display an icon, this will appear as the icon for the action. Defaul is null

  • disabledboolean

    This tells the render context whether to disable this action. Default is false.

  • shortcutstring

    A keyboard shortcut that should trigger the action. The keyboard shortcut must be compatible with the format supported by the is-hotkey-package.

  • titlestring

    A title for the action. Depending on the render context this will be used as tooltip title (e.g. for buttons it may be passed as the title attribute). Default is null.

  • dialogConfirmDialog | PopOverDialog | ModalDialog

    If this is returned, its value will be turned into a dialog by the render context. More about dialog types below. Default is null.

Document Action dialog types

Dialogs can be use to inform users about your action, or collect confirmation before executing the action. There are three types of dialogs:

Examples of the different dialog types

Confirm dialog

This tells the render context to display a confirm dialog.

Properties

  • typestring

    Must be confirm.

  • colorstring

    Support the following values warning, success, danger, info.

  • messagestring | React.ReactNode

    The message that will be shown in the dialog.

  • onConfirmfunction

    A function to execute when the the user confirms the dialog.

  • onCancelfunction

    A function to execute when the user cancels the dialog.

Example

export function ConfirmDialogAction({onComplete}) {
  const [dialogOpen, setDialogOpen] = React.useState(false)
  return {
    label: 'Show confirm',
    onHandle: () => {
      setDialogOpen(true)
    },
    dialog: dialogOpen && {
      type: 'confirm',
      onCancel: onComplete,
      onConfirm: () => {
        alert('You confirmed!')
        onComplete()
      },
      message: 'Please confirm!'
    }
  }
}

Popover

This will display the value specified by the content property in a popover dialog. The onClose property is required, and will normally be triggered by click outside or closing the popover.

  • typestring

    Must be popover.

  • contentstring | React.ReactNode

    The content to be shown in the popover dialog.

  • REQUIREDonClosefunction

    A function to execute when the dialog is closed.

Example

export function PopoverDialogAction({onComplete}) {
  const [dialogOpen, setDialogOpen] = React.useState(false)
  return {
    label: 'Show popover',
    onHandle: () => {
      setDialogOpen(true)
    },
    dialog: dialogOpen && {
      type: 'popover',
      onClose: onComplete,
      content: "👋 I'm a popover!"
    }
  }
}

Modal

This will display the value specified by the content property in a modal dialog. The onClose property is required.

  • typestring

    Must be modal.

  • titlestring

    A title to show in the title field of the modal dialog.

  • contentstring | React.ReactNode

    The content to show in the modal dialog.

  • REQUIREDonClosefunction

    A function to execute when the modal is closed by the user.

Example

export function ConfirmDialogAction({onComplete}) {
  const [dialogOpen, setDialogOpen] = React.useState(false)
  return {
    label: 'Show confirm',
    onHandle: () => {
      setDialogOpen(true)
    },
    dialog: dialogOpen && {
      type: 'modal',
      onClose: onComplete,
      content: <div>
        <h3>👋 ... and I'm a modal</h3>
        <img src="https://source.unsplash.com/1600x900/?cat" style={{width: '100%'}}/>
        <p>
          I'm suitable for longer and more diverse forms of content.
        </p>
      </div>    
    }
  }
}

Was this article helpful?