> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# 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.

```typescript
// sanity.config.ts
import {defineConfig} from 'sanity'

export default defineConfig({
  /* ... */
  document: {
    newDocumentOptions: (prev, {currentUser, creationContext}) => {
      /* ... */
      return prev
    }
  }
})
```

> [!TIP]
> Pro tip
> 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

#### Properties

**prev** (array | TemplateItem[])

An array containing all available template items.

**context** (object | 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

#### Properties

**creationContext** (object | 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.

**currentUser** (object | CurrentUser)

An object containing details about the current user such as id, roles, and email.

## Usage examples

### Example: Limit document types by role

```typescript
// 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.some((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

```typescript
// 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

> [!TIP]
> FYI
> Starting in Studio version `6.17.0`, [there’s a dedicated API for creating singletons](https://www.sanity.io/docs/studio/create-a-link-to-a-single-edit-page-in-your-main-document-type-list). If you use that API, there’s no need to configure a filter for `newDocumentOptions`.

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**

```typescript
// sanity.config.ts
import {defineConfig} from 'sanity'

export default defineConfig({
  /* ... */
  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:

**structure.ts**

```typescript
// structure.ts (or your structure file)
import {type 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')
            .apiVersion('2025-02-19')
            .filter('_type == "post" && !(_id in path("drafts.**"))')
            .initialValueTemplates([])
        ),
    ])
```

Learn more about Structure Builder configuration in the [Structure Builder reference](https://www.sanity.io/docs/studio/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:

**sanity.config.ts**

```typescript
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](https://www.sanity.io/docs/studio/initial-value-templates): define templates with prefilled values for new documents.
- [Structure Builder reference](https://www.sanity.io/docs/studio/structure-builder-reference): configure the Studio layout, including the create button in panes.
- [Document actions](https://www.sanity.io/docs/studio/document-actions): customize the publish, delete, and other actions available on documents.



## Related changelog entries

Entries are listed newest first; each link points to the full entry as markdown. Follow one when you need to know what changed, when, or why — for example, to summarize recent updates, explain behavior that differs from older documentation, or check whether a fix has shipped.

- [Sanity Studio v6.17.0: First-class singletons and document counts, plus faster tool switching, and form and Presentation fixes](https://www.sanity.io/docs/changelog/studio-Ni4xNi4w.md) — September 29, 2026