New Document Options
Customize the new document creation experience for creators in Sanity Studio.
The newDocumentOptions API allows you to customize the new document choices users see when they interact with the Create buttons in Sanity Studio.
document.newDocumentOptions accepts a callback function that returns an array of new document option templates. The callback accepts an array of existing templates, commonly displayed as prev, and a context object as arguments. It should return an array of template items.
// sanity.config.ts
import {defineConfig} from 'sanity'
export default defineConfig({
/* ... */
document: {
newDocumentOptions: (prev, {currentUser, creationContext}) => {
/* ... */
return prev
}
}
})Protip
It's common to return a subset of existing types by filtering and returning the prev array, but you can also add new templates as part of the callback.
Callback parameters
prevarray | TemplateItem[]
An array containing all available template items.
contextobject | NewDocumentOptionsContext
Contains details about the context of the new document creation. Useful for comparing details about the current user and where the document creation event was initiated.
Context properties
creationContextobject | NewDocumentCreationContext
An object containing the type (global, document, or structure) and the schemaType, if one exists. Useful for determining where the document creation action originated.
currentUserobject | CurrentUser
An object containing details about the current user such as id, roles, and email.
Usage examples
Example: Limit document types by role
// sanity.config.ts
import {defineConfig} from 'sanity'
// Create an array of templateId strings.
// These can match initial value templates, or document names.
const contributor_templates = [
'guide',
'blogPost',
'caseStudy',
]
export default defineConfig({
/* ... */
document: {
newDocumentOptions: (prev, {currentUser}) => {
// Check if the current user is not an administrator
if (currentUser?.roles.find((role) => role.name !== 'administrator')) {
return prev.filter(({templateId}) => contributor_templates.includes(templateId))
}
// All other users (Administrators) see the full document list
return prev
}
}
})Example: Hide a specific document type from the global create menu
// sanity.config.ts
import {defineConfig} from 'sanity'
export default defineConfig({
/* ... */
document: {
newDocumentOptions: (prev, {currentUser, creationContext}) => {
if (creationContext.type === 'global') {
// Hide the creation of "settings" documents if the context is global
return prev.filter((templateItem) => templateItem.templateId != 'settings')
}
return prev
}
}
})Common patterns
Hide a singleton from the create menu
Singleton documents (like site settings) should not appear in the global create menu since only one instance should exist. Filter them out by template ID:
// sanity.config.ts
import {defineConfig} from 'sanity'
export default defineConfig({
// ...rest of config
document: {
newDocumentOptions: (prev, {creationContext}) => {
if (creationContext.type === 'global') {
return prev.filter(
(templateItem) => !['siteSettings', 'navigation'].includes(templateItem.templateId)
)
}
return prev
},
},
})Hide the create button in a Structure pane
To remove the "+" button from a specific list in the Structure Builder, set initialValueTemplates to an empty array. This is useful for read-only lists or filtered views where creating new documents does not make sense:
// deskStructure.ts (or your structure file)
import {StructureBuilder} from 'sanity/structure'
export const structure = (S: StructureBuilder) =>
S.list()
.title('Content')
.items([
S.listItem()
.title('Published posts')
.child(
S.documentTypeList('post')
.title('Published posts')
.filter('_type == "post" && !(_id in path("drafts.**"))')
.initialValueTemplates([])
),
])Learn more about Structure Builder configuration in the Structure Builder reference.
Different options for different contexts
The creationContext.type parameter tells you where the create action is happening. Use it to show different options in the global menu versus within a Structure pane:
document: {
newDocumentOptions: (prev, {creationContext}) => {
// In the global "+" menu, only show 'article' and 'author'
if (creationContext.type === 'global') {
return prev.filter((templateItem) =>
['article', 'author'].includes(templateItem.templateId)
)
}
// In Structure panes, show all options
return prev
},
}Related resources
- Initial Value Templates: define templates with prefilled values for new documents
- Structure Builder reference: configure the Studio layout, including the create button in panes
- Document actions: customize the publish, delete, and other actions available on documents