
Grab your gear: The official Sanity swag store
Read Grab your gear: The official Sanity swag storeBased on what you're describing, you're on the right track! This is a classic page builder pattern in Sanity, and there are a couple of ways to structure it depending on your needs.
You have two architectural options for connecting components to pages:
Define your components as object types and embed them directly in the page's array. This is like having the component data live "inside" the page document:
// Component schemas (objects, not documents)
export const hero = {
name: 'hero',
type: 'object',
fields: [
{name: 'heading', type: 'string'},
{name: 'image', type: 'image'},
{name: 'cta', type: 'object', fields: [...]},
]
}
// Page schema
export const page = {
name: 'page',
type: 'document',
fields: [
{name: 'title', type: 'string'},
{
name: 'content',
type: 'array',
of: [
{type: 'hero'},
{type: 'features'},
{type: 'faq'},
// ... other component types
]
}
]
}Pros: Simpler queries, content stays with the page, easier to manage
Cons: Can't reuse the exact same hero instance across multiple pages
Make your components actual documents and reference them:
// Component as document
export const hero = {
name: 'hero',
type: 'document',
fields: [...]
}
// Page references components
export const page = {
name: 'page',
type: 'document',
fields: [
{
name: 'content',
type: 'array',
of: [{type: 'reference', to: [{type: 'hero'}, {type: 'features'}]}]
}
]
}Pros: Can reuse exact component instances across pages
Cons: More complex queries (need to resolve references), more documents to manage
For most page builders, go with inline objects (approach #1). This matches your "instance of a component" mental model from relational databases - each time you add a hero to a page, you're creating a new instance with its own data.
The Sanity page building course covers this exact pattern in detail and shows how to structure your component schemas, add custom previews so editors see what they're building, and handle rendering on the frontend.
Only use references if you specifically need to share the exact same content across multiple pages (like a global announcement banner that should update everywhere when changed).
title and preview configuration so content editors can easily identify blocksicon property to each component type for better visual scanning in the StudioThe beauty of this approach is that adding a new component type just means adding it to the of array, and it immediately becomes available to all pages!
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.
Content operations
Content backend


The only platform powering content operations
By Industry


Tecovas strengthens their customer connections
Build and Share

Grab your gear: The official Sanity swag store
Read Grab your gear: The official Sanity swag store