How to create a singleton document that can only be created once in Sanity?
Yes, absolutely! This is called a singleton document in Sanity, and it's perfect for things like landing pages, headers, footers, or site settings that should only exist once.
To create a singleton document, you need to configure three things in your sanity.config.ts (or .js) file:
1. Define your singleton types
First, create a Set of your singleton schema type names:
const singletonTypes = new Set(['siteSettings', 'header', 'footer'])
const singletonActions = new Set(['publish', 'discardChanges', 'restore'])2. Configure the Structure Builder
Set up direct links to your singleton documents (no list view):
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
export default defineConfig({
plugins: [
structureTool({
structure: (S) =>
S.list()
.title('Content')
.items([
S.listItem()
.title('Site Settings')
.id('siteSettings')
.child(
S.document()
.schemaType('siteSettings')
.documentId('siteSettings')
),
S.listItem()
.title('Header')
.id('header')
.child(
S.document()
.schemaType('header')
.documentId('header')
),
// ... other items
])
})
]
})3. Filter templates and actions
Prevent users from creating duplicates or deleting singletons:
export default defineConfig({
// ... other config
schema: {
types: [/* your schemas */],
// Hide singleton types from the "Create new document" menu
templates: (templates) =>
templates.filter(({ schemaType }) => !singletonTypes.has(schemaType))
},
document: {
// Remove duplicate and delete actions for singletons
actions: (input, context) =>
singletonTypes.has(context.schemaType)
? input.filter(({ action }) => action && singletonActions.has(action))
: input
}
})Important Note
You need to create the singleton document manually first (before adding it to the singletonTypes set), since the configuration will prevent you from creating new instances through the UI.
Easier Alternative
If you want a simpler setup, check out the singleton-tools plugin which handles all this configuration for you automatically!
This pattern is covered in detail in the official singleton document guide, which includes complete examples for all three configuration steps.
Show original thread8 replies
Sanity – Build the way you think, not the way your CMS thinks
Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.